section-gettingstarted.tex

\chapter{Getting Started}

\section{Documentation Conventions}

Items to be selected from a menu are displayed in \menustyle{monospace font}.

Multilevel menu paths are separated by a / character. For example, \menustyle{Attenuation / 1x} means to open the
\menustyle{Attenuation} submenu and select the \menustyle{1x} item.

If there are multiple options for a menu or configuration option, they are displayed in square brackets and separated
by a | character. For example, \menustyle{Move waveform to / Waveform Group [1|2]} means to select either
\menustyle{Waveform Group 1} or \menustyle{Waveform Group 2} from the \menustyle{Move waveform to}
menu.

This project is under active development and is not anywhere near feature complete! As a result, this document is
likely to refer to active bug or feature request tickets on the GitHub issue trackers. Issues are referenced as
repository:ticket, for example scopehal-apps:3.

\section{Host System Requirements}

The majority of development is performed on Linux operating systems (primarily Debian and Arch), although experimental
Windows support is available. glscopeclient uses gtkmm as the UI toolkit. Current development mostly uses 3.24 but any
recent 3.x version should work.

Any 64-bit Intel or AMD processor should be able to run glscopeclient. If AVX2 and/or AVX512F support is present
glscopeclient will use special optimized versions of some signal processing functions, however neither instruction set
is required. Compiling in 32-bit mode is not supported due to the significant RAM requirements.

A mouse with scroll wheel, or touchpad with scroll gesture support, is mandatory to enable full use of the UI. We may
explore alternative input methods for some UI elements in the future.

OpenGL 4.2 or later is required, as well as several extensions:
\begin{itemize}
\item GL\_ARB\_arrays\_of\_arrays (or OpenGL 4.3)
\item GL\_ARB\_compute\_shader (or OpenGL 4.3)
\item GL\_ARB\_shader\_storage\_buffer\_object (or OpenGL 4.3)
\item GL\_EXT\_blend\_equation\_separate
\end{itemize}

The corresponding minimum hardware requirement is an AMD Radeon HD 5000, NVIDIA GeForce GTX 6xx series discrete GPU, or
Intel Skylake or newer integrated GPU, plus suitably up-to-date drivers. On Linux with recent Mesa, Intel integrated
GPUs as old as Ivy Bridge may be used.

TODO: what AMD integrated/ARM GPUs started supporting GL 4.2?

To check for necessary graphics card support on Linux:
\begin{lstlisting}[language=sh]
glxinfo | grep GL\_ARB\_arrays\_of\_arrays
glxinfo | grep GL\_ARB\_compute\_shader
glxinfo | grep GL\_ARB\_shader\_storage\_buffer\_object
glxinfo | grep GL\_EXT\_blend\_equation\_separate
glxinfo | grep "OpenGL version string"
\end{lstlisting}

If OpenCL 1.2 or higher is present, some filters may make use of GPU acceleration. As of this writing the first
detected GPU is automatically used; there may be a way to select specific devices in the future.

The minimum RAM requirement to actually launch glscopeclient is relatively small (the default demo configuration uses
under 512 MB) however history mode and deep captures can easily consume many GB of RAM very rapidly. We suggest 8GB as
a reasonable minimum, with 32 or more encouraged for deep history.

\section{Instrument Support}

glscopeclient uses the libscopehal library to communicate with oscilloscopes, so any libscopehal-compatible hardware
should work with glscopeclient. See the \hyperref[sec:drivers]{Oscilloscope Drivers} section for more details on which
hardware is supported and how to configure specific drivers.

\section{Compilation}

glscopeclient can be compiled on both Linux and Windows, but the specific steps that have to be taken differ quite a
lot between these the two.

\subsection{Linux}
\begin{enumerate}

\item Install dependencies.

On Debian/Ubuntu:

\begin{lstlisting}[language=sh]
sudo apt install build-essential cmake pkg-config libglm-dev \
	libgtkmm-3.0-dev libsigc++-2.0-dev libyaml-cpp-dev \
	liblxi-dev texlive texlive-fonts-extra libglew-dev \
	catch2 libclfft-dev
\end{lstlisting}

On Fedora:

\begin{lstlisting}[language=sh]
sudo dnf install gtkmm30-devel cmake pkg-config glm-devel \
	texlive libyaml-devel yaml-cpp-devel glew-devel \
	catch-devel
\end{lstlisting}

If you are using an older stable release (such as Debian Buster), you may need to install catch2 from source
(https://github.com/catchorg/Catch2). Alternatively, you may pass -DBUILD\_TESTING=OFF to CMake to disable unit testing.

\item Install FFTS library:

\begin{lstlisting}[language=sh]
git clone https://github.com/anthonix/ffts.git
cd ffts
mkdir build
cd build
cmake .. -DENABLE_SHARED=ON
make -j4
sudo make install
\end{lstlisting}

\item Build scopehal and scopehal-apps:

\begin{lstlisting}[language=sh]
git clone https://github.com/azonenberg/scopehal-apps.git --recurse-submodules
cd scopehal-apps
mkdir build
cd build
cmake ../ -DCMAKE_BUILD_TYPE=RELEASE -DCMAKE_INSTALL_PREFIX=/usr
make -j4
\end{lstlisting}

\item Install scopehal and scopehal-apps:

\begin{lstlisting}[language=sh]
make install
\end{lstlisting}

\end{enumerate}

\subsection{Windows}

On Windows, we make use of the MSYS2 development environment, which gives us access to the MingGW-w64 toolchain.
Since this toolchain allows glscopeclient to be compiled as a native Windows application, the project might be run
outside of MSYS2.

\subsubsection{Installing from the package manager}

\begin{lstlisting}[language=sh]
pacman -Sy
pacman -S mingw-w64-x86_64-scopehal-apps
\end{lstlisting}

See also \href{https://packages.msys2.org/group/mingw-w64-x86_64-eda}{\lstinline{mingw-w64-x86_64-eda}}.

\subsubsection{Building from source}

\begin{enumerate}

\item Download and install MSYS2. You can download it from \href{https://www.msys2.org/}{msys2.org} or \href{https://github.com/msys2/msys2-installer/releases}{github.com/msys2/msys2-installer/releases}\\
It is of utmost importance that \textbf{all} steps outlined on the website are followed precisely, even if they might
seem unnecessary.
This will avoid lots of hard to diagnose problems later on in the build.\\

All following steps are to be done in a MinGW64 shell (\textbf{not} in a MSYS, MINGW32, CLANG64, CLANG32 or UCRT64 shell,
which also get installed by the MSYS2 installer).

\item Install git and the toolchain:

\begin{lstlisting}[language=sh]
pacman -S git mingw-w64-x86_64-toolchain
\end{lstlisting}

\item Check out the code

\begin{lstlisting}[language=sh]
git clone --recursive https://github.com/azonenberg/scopehal-apps
cd scopehal-apps
\end{lstlisting}

\item Execute makepkg-mingw in subdir MSYS2:

\begin{lstlisting}[language=sh]
cd msys2
MINGW_ARCH=mingw64 makepkg-mingw --noconfirm --noprogressbar -sCLf
\end{lstlisting}

The unit tests will not be run as part of this build - if you would like to run them, you will need to provide catch2
(https://github.com/catchorg/Catch2), and remove the -DBUILD\_TESTING=OFF flag from the PKGBUILD recipe in subdir
msys2.

\item Installing, copying binaries and running glscopeclient.

Since glscopeclient is built using the MinGW toolchain, it depends on a rather large number of dynamic libraries.
The recommended procedure is to install the package generated by makepkg-mingw on a MinGW64 shell:

\begin{lstlisting}[language=sh]
cd msys2
pacman -U *.zst
\end{lstlisting}

This is equivalent to the package installed through \lstinline{pacman -S}, but it's built from the checked out commit,
instead of the pinned version available from MSYS2 repositories.

The \lstinline{*.zst} package includes metadata about the dependencies.
Therefore, when installed through \lstinline{pacman}, those will be installed automatically.
However, some users might want to use glscopeclient outside of MSYS2.
In those cases, it needs to be installed first, and then a tarball/zipfile can be created by collecting all the dependencies.
This last approach is not officially supported yet.

\end{enumerate}

\section{Running glscopeclient}

When running glscopeclient with no arguments, an empty session (Fig. \ref{empty-window}) is created. To perform useful
work, you can:
\begin{itemize}
\item Open a saved session (\menustyle{File | Open})
\item Import waveforms from an external data file (\menustyle{File | Import})
\item Connect to an instrument (\menustyle{File | Connect})
\item Reconnect to a recently used instrument (\menustyle{File | Recent Instruments})
\item Generate a synthetic waveform (\menustyle{Add | Generate})
\end{itemize}

\begin{figure}[h]
\centering
\includegraphics[width=10cm]{images/empty-window.png}
\caption{Empty glscopeclient session}
\label{empty-window}
\end{figure}

\subsection{Configuration arguments}

Most of these arguments are intended for developers, but they can help troubleshoot unusual bugs.

\begin{itemize}

\item \texttt{--noglint64}\\
Do not use \texttt{GL\_ARB\_gpu\_shader\_int64} even if the GPU supports it.

\item \texttt{--noopencl}\\
Do not use OpenCL even if a supported GPU or accelerator is present.

\end{itemize}

\subsection{Console verbosity arguments}

glscopeclient takes standard liblogtools arguments for controlling console debug verbosity.

If no verbosity level is specified, the default is ``notice" (3). (We suggest using \texttt{--debug} for routine use
until the v1.0 release to aid in troubleshooting.)

\begin{itemize}

\item \texttt{--debug}\\
Sets the verbosity level to ``debug" (5).

\item \texttt{-l [file]}, \texttt{--logfile [file]}\\
Writes a copy of all log messages to \texttt{file}. This is preferred over simply redirecting output with pipes, as
console escape sequences are stripped from the file log output.

\item \texttt{-L [file]}, \texttt{--logfile-lines [file]}\\
Same as \texttt{--logfile} except line buffering is turned on.

\item \texttt{-q}, \texttt{--quiet}\\
Reduces the verbosity level by one. Can be specified more than once to lower verbosity by several steps.

\item \texttt{--trace [class]}, \texttt{--trace [class::function]} \\
Enables extra debug output from the class \texttt{class} or the function \texttt{class::function}. Has no effect unless
\texttt{--debug} is also specified.

\item \texttt{--stdout-only}\\
Sends all logging output to stdout. By default, error (level 1) and warning (level 2) messages go to stderr.

\item \texttt{--verbose}\\
Sets the verbosity level to ``verbose" (4).

\end{itemize}

\subsection{File arguments}
\label{import}

The file extension is used to determine the format. File extensions are case sensitive and must be lowercase to be
correctly interpreted.

\begin{itemize}
\item \texttt{[file.scopesession]}
Loads a saved session.

\item \texttt{[file.bin]} \\
Imports waveform data from the binary format used by Agilent, Keysight, and Rigol oscilloscopes.

\item \texttt{[file.complex]} \\
Imports complex I/Q data from a file. The file must contain interleaved (I, Q) pairs in either 8-bit signed integer,
16-bit signed integer, 32-bit normalized floating point, or 64-bit normalized floating point format.

glscopeclient uses a heuristic to determine the correct sample format. The first 1024 bytes of the file are loaded
using all four possible formats, and the average I/Q magnitude is used to create a score. After excluding floating
point formats with a maximum magnitude less than 1e-6, the score closest to zero is considered the correct format and
the remainder of the file is parsed using this format.

If the file name contains the string "MSps" (case sensitive), digits left of the string are assumed to be a sample rate
in millions of samples per second. If this string is not found, the sample rate is assumed to be 1 Msps.

\item \texttt{[file.csv]} \\
Imports sample data from a CSV (comma-separated-value) file. More than one CSV file can be loaded at once (displayed as
separate points in history) by specifying multiple file names as long as they have identical column schemas.

Lines starting with a '\#' character are treated as comments and generally ignored by the parser. (If the comment format
matches that used by Digilent's WaveForms utility, timestamps and other metadata are extracted from the comments.)

If the first row of the CSV contains non-numeric characters, it is treated as a header row. Header content in the
timestamp column is ignored; headers in other columns are used as channel names in the imported waveform.

The first column of the CSV must contain sample timestamps, in seconds. Scientific notation is supported. Timestamps
must be monotonic (each row must have a timestamp strictly greater than that of the previous row).

glscopeclient uses a heuristic to detect uniformly sampled waveforms, which enabled certain optimizations for display
and signal processing. If the standard deviation of intervals between samples is less than 1\% of the average sample
interval, the waveform is assumed to be uniformly sampled and timestamps are rounded to the nearest multiple of the
average interval. If the deviation is greater, the waveform is assumed to be sparsely sampled and timestamps are not
modified.

\item \texttt{[file.vcd]} \\
Imports digital waveform data from a VCD (value change dump) file, typically created by a logic analyzer or HDL
simulator.

\item \texttt{[file.wav]} \\
Imports sample data from a WAV file. More than one WAV file can be loaded at once (displayed as separate points in
history) by specifying multiple file names as long as they have identical sample rates and channel counts.

\item \texttt{--nodata}\\
When loading a .scopesession file, load settings only and not saved waveform data.

\item \texttt{--reconnect}\\
When loading a .scopesession file, reconnect to the instrument and resume remote control. Current instrument settings
are overwritten with the configuration from the saved session.

\item \texttt{--retrigger}\\
When loading a .scopesession file, arm the trigger immediately. has no effect unless \texttt{--reconnect} is also
specified.

\end{itemize}

\subsection{Instrument arguments}

Example:
\begin{lstlisting}[language=sh]
./glscopeclient --debug \
	mylecroy:lecroy:vicp:myscope.example.com:1234 \
	myrigol:rigol:lan:rigol.example.com
\end{lstlisting}

\begin{itemize}
\item \texttt{[connection string]} \\
Connects to the specified instrument. By default, all channels are enabled and displayed.

\item \texttt{--nodigital} \\
Do not enable MSO channels at startup. This does not prevent MSO channels from being added to the session later.

\item \texttt{--nospectrum}
Do not enable spectrum analyzer channels at startup. This does not prevent spectrum analyzer channels from being added
to the session later.

\end{itemize}

Each instrument is described by a ``connection string" containing four colon-separated fields.

\begin{itemize}
\item Nickname. This can be any text string not containing spaces or colons. If you have only one instrument it's
largely ignored, but when multiple instruments are present channel names in the UI are prefixed with the nickname to
avoid ambiguity.
\item Driver name. This is a string identifying the command protocol the scope uses. Note that not all
scopes from the same vendor will use the same command set or driver!
\item Transport. This is is a string describing how the driver connects to the scope (e.g. RS232 or Ethernet)
\item Arguments for the driver identifying the device to connect to, separated by colons. This varies by driver but is
typically a hostname:port combination, TTY device path, or similar.
\end{itemize}

\section{Design Philosophy}

glscopeclient's UI is heavily mouse driven and context based. Space used by always-visible buttons, sliders, etc is
kept to a minimum in order to keep as much screen real estate as possible usable for waveform display. Additional
controls are displayed in menus or pop-up dialogs, then hidden as soon as they are not needed.

Most UI elements can be interacted with by left clicking (select), left dragging (move), using the scroll wheel (zoom),
double clicking (open properties dialog), or right clicking (context menu).

If you have a multi-button gaming mouse, button 8 stops the trigger and button 9 starts. These bindings are not
currently configurable.

Most text fields allow SI prefixes for scaling values (mV, us, GHz, etc).

\section{Troubleshooting}

\subsection{Corrupted or no graphical output in waveform areas}

Some users have reported problems with libglvnd under Linux. Changing the CMP0072 declaration in
glscopeclient/CMakeLists.txt from NEW to OLD may fix it.