Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: ngscopeclient/scopehal-docs
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: c283bd9e9d10
Choose a base ref
...
head repository: ngscopeclient/scopehal-docs
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: 9434abdeb797
Choose a head ref
  • 2 commits
  • 13 files changed
  • 1 contributor

Commits on May 25, 2020

  1. Copy the full SHA
    ee169c0 View commit details
  2. Copy the full SHA
    9434abd View commit details
6 changes: 6 additions & 0 deletions glscopeclient-manual.tex
Original file line number Diff line number Diff line change
@@ -94,6 +94,12 @@
\pagebreak
\include{section-waveformgroups}

\pagebreak
\include{section-timeline}

\pagebreak
\include{section-waveformviews}

\pagebreak
\include{section-history}

Binary file added images/eye-gradient-crt.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/eye-gradient-grayscale.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/eye-gradient-ironbow.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/eye-gradient-krain.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/eye-gradient-rainbow.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/eye-gradient-viridis.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified images/multiple-groups.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified images/overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
34 changes: 34 additions & 0 deletions section-mainwindow.tex
Original file line number Diff line number Diff line change
@@ -7,12 +7,46 @@ \subsection{Menu}

\subsubsection{File}

This menu contains commands for manipulating glscopeclient session files.

A session consists of a YAML file called filename.scopesession containing instrument and UI configuration, as well
as a directory called filename\_data which contains waveform metadata and sample values for all enabled instrument
channels.

\textbf{Save}: The UI layout may be saved to a session file so that a common instrument setup can be returned to in the
future. Waveform data may optionally be saved in the session as well.

\textbf{Open}: Loads a .scopesession file. Checkboxes at the bottom of the file browser dialog allow the UI
configuration, instrument settings, and waveform data to be individually loaded or ignored.

\textbf{Quit}: Exits the application

\subsubsection{Setup}

This menu allows instrument settings to be configured. Currently there's not much here.

\subsubsection{View}

This menu allows display settings to be configured. As of now, the only option is selection of the color palette for
eye patterns.

\begin{tabularx}{16cm}{llX}
\thickhline
\textbf{Name} & \textbf{Colors} & \textbf{Notes} \\
\thickhline
CRT & \includegraphics[width=5cm]{images/eye-gradient-crt.png} & Similar color scheme to a major scope vendor.\\
Grayscale & \includegraphics[width=5cm]{images/eye-gradient-grayscale.png} & Common monochrome palette.\\
Ironbow & \includegraphics[width=5cm]{images/eye-gradient-ironbow.png} & Common "hot metal" palette. \\
KRain & \includegraphics[width=5cm]{images/eye-gradient-krain.png} & Similar color scheme to a major scope vendor.\\
Rainbow & \includegraphics[width=5cm]{images/eye-gradient-rainbow.png} & Common HSV rainbow palette. \\
Viridis & \includegraphics[width=5cm]{images/eye-gradient-viridis.png} & Perceptually uniform palette from matplotlib. \\
\thickhline
\end{tabularx}

\subsubsection{Add}

This menu allows a new waveform view to be created for any channel on a connected instrument.

\subsection{Toolbar}

The toolbar contains buttons and controls for the most frequently used actions.
14 changes: 14 additions & 0 deletions section-timeline.tex
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@

\section{Timeline}

The timeline is displayed at the top of each waveform group and shows the X axis scale for the group. The timeline (and
all accompanying waveform views in the group) may be zoomed by scrolling with the mouse wheel, or panned by dragging
with the left mouse button.

Unlike classical oscilloscope user interfaces, there is \emph{no relationship} between the timeline scale/position and
the duration of the acquisition. It is possible to zoom or scroll beyond the end of the acquisition (displaying empty
background with no signal) or have a deep capture in which nearly all acquired data is offscreen.

TODO: talk about how to set trigger offset in capture and change timebase once that's implemented

TODO: insert screenshot after we have some pending UI changes done
113 changes: 10 additions & 103 deletions section-waveformgroups.tex
Original file line number Diff line number Diff line change
@@ -37,10 +37,16 @@ \subsection{Managing Groups}
vertically, with the selected waveform moved or copied to the newly added group and all other waveforms in the original
group.

Waveforms may be also be moved within, or between, groups by clicking the channel information box and dragging it. A
yellow insertion bar will appear when dragging, showing the location the waveform will be inserted in.

If a waveform is dragged to the very bottom or right side of a waveform group, the destination group will be split
vertically or horizontally and the new waveform will be inserted below or to the right of the destination group. The
insertion bar turns orange when dragging near the edge of a group, to indicate that a split will take place.

Dividers between waveform groups may be dragged with the left mouse button. Any group may be subdivided again, to
create arbitrarily complex tiles of waveforms. Figure \ref{multiple-groups} shows a two-level hierarchy created by
moving channel 2 to a new group at right, moving channel 4 to this group, then moving channel 4 again a new group at
bottom.
moving channel 2 to a new group at right, then moving channel 4 to a new group below that one.

\begin{figure}[h]
\centering
@@ -49,107 +55,8 @@ \subsection{Managing Groups}
\label{multiple-groups}
\end{figure}

A future software release will support using the mouse to move and copy waveforms, both between groups and within a
group (scopehal-apps:6). The exact semantics for this are not yet defined.
Protocol decode overlays may be reordered by dragging the channel information box with the mouse, however they cannot
currently be moved to another waveform or group.

New waveform groups are given an automatically generated name when created, for example "Waveform Group 2". This name
will be editable in a future software release (scopehal-apps:53).

\pagebreak
\section{Timeline}

The timeline is displayed at the top of each waveform group and shows the X axis scale for the group. The timeline (and
all accompanying waveform views in the group) may be zoomed by scrolling with the mouse wheel, or panned by dragging
with the left mouse button.

Unlike classical oscilloscope user interfaces, there is \emph{no relationship} between the timeline scale/position and
the duration of the acquisition. It is possible to zoom or scroll beyond the end of the acquisition (displaying empty
background with no signal) or have a deep capture in which nearly all acquired data is offscreen.

TODO: talk about how to set trigger offset in capture and change timebase once that's implemented

TODO: insert screenshot after we have some pending UI changes done

\pagebreak
\section{Waveform Views}

A waveform view is a 2D graph of a signal or protocol decode within a waveform group.

\subsection{Plot Area}

The plot area shows the waveform being displayed. The background has a subtle gradient from light at top to dark at
bottom, in order to visually separate adjacent waveform view within the same group.

The horizontal grid lines line up with the voltage scale markings on the Y axis. If the plot area includes Y=0, the
grid line for zero is slightly brighter.

\begin{figure}[H]
\centering
\includegraphics[width=10cm]{images/waveform-graph.png}
\caption{Waveform plot area}
\label{waveform-graph}
\end{figure}

The waveform is drawn as a semi-transparent line so that when zoomed out, the density of voltage at various points in
the graph may be seen as lighter or darker areas. This is referred to as ``intensity grading".

\begin{figure}[H]
\centering
\includegraphics[width=10cm]{images/graded-waveform.png}
\caption{Intensity-graded waveform}
\label{graded-waveform2}
\end{figure}

\subsection{Y Axis Scale}

Each waveform view has its own Y axis scale, which is locked to the ADC range of the instrument.

Dragging the Y axis scale with the left mouse button currently does nothing (scopehal-apps:54) but in a future software
release will change the voltage offset of the channel.

Scrolling the Y axis scale with the mouse wheel changes the gain of the channel.

If a left-pointing arrow (as seen in Fig. \ref{y-axis}) is visible, the current channel is selected as a trigger
source. Click on the arrow and drag up or down to select the trigger level.

\begin{figure}[H]
\centering
\includegraphics[height=3cm]{images/y-axis.png}
\caption{Y axis of a waveform view showing trigger arrow}
\label{y-axis}
\end{figure}

\subsection{Channel Information Box}

The channel information box is displayed in the lower left corner of each waveform view. It contains summary
information about the channel. Currently this is the display name of the channel, the sample rate, and the record
length of the acquisition. Other information, such as probe coupling, may be displayed there in the future.

Double-clicking the information box opens the channel properties dialog.

\begin{figure}[H]
\centering
\includegraphics[width=2cm]{images/channel-infobox.png}
\caption{Channel information box}
\label{channel-infobox}
\end{figure}

\subsection{Overlays}

Waveforms may have additional information overlaid on top of them, such as protocol decodes. Each overlay has its own
information box, which may be double-clicked to open the properties dialog and configure it just like any other
channel.

Fig. \ref{overlays} shows
an example of an analog waveform with three overlays: thresholding it to NRZ digital, recovering a sampling
clock with a CDR PLL, and finally decoding the serial NRZ data stream to TMDS protocol data and control events.

\begin{figure}[H]
\centering
\includegraphics[width=14cm]{images/overlays.png}
\caption{Waveform showing two digital overlays and a data decode overlay}
\label{overlays}
\end{figure}

Overlays can be deleted but cannot currently be moved between waveform areas or reordered within a single waveform area
(scopehal-apps:7, scopehal-apps:6)
82 changes: 82 additions & 0 deletions section-waveformviews.tex
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
\section{Waveform Views}

A waveform view is a 2D graph of a signal or protocol decode within a waveform group.

\subsection{Plot Area}

The plot area shows the waveform being displayed. The background has a subtle gradient from light at top to dark at
bottom, in order to visually separate adjacent waveform view within the same group.

The horizontal grid lines line up with the voltage scale markings on the Y axis. If the plot area includes Y=0, the
grid line for zero is slightly brighter.

\begin{figure}[H]
\centering
\includegraphics[width=10cm]{images/waveform-graph.png}
\caption{Waveform plot area}
\label{waveform-graph}
\end{figure}

The waveform is drawn as a semi-transparent line so that when zoomed out, the density of voltage at various points in
the graph may be seen as lighter or darker areas. This is referred to as ``intensity grading".

\begin{figure}[H]
\centering
\includegraphics[width=10cm]{images/graded-waveform.png}
\caption{Intensity-graded waveform}
\label{graded-waveform2}
\end{figure}

\subsection{Y Axis Scale}

Each waveform view has its own Y axis scale, which is locked to the ADC range of the instrument.

Dragging the Y axis scale with the left mouse button currently does nothing (scopehal-apps:54) but in a future software
release will change the voltage offset of the channel.

Scrolling the Y axis scale with the mouse wheel changes the gain of the channel.

If a left-pointing arrow (as seen in Fig. \ref{y-axis}) is visible, the current channel is selected as a trigger
source. Click on the arrow and drag up or down to select the trigger level.

\begin{figure}[H]
\centering
\includegraphics[height=3cm]{images/y-axis.png}
\caption{Y axis of a waveform view showing trigger arrow}
\label{y-axis}
\end{figure}

\subsection{Channel Information Box}

The channel information box is displayed in the lower left corner of each waveform view. It contains summary
information about the channel. Currently this is the display name of the channel, the sample rate, and the record
length of the acquisition. Other information, such as probe coupling, may be displayed there in the future.

Double-clicking the information box opens the channel properties dialog.

\begin{figure}[H]
\centering
\includegraphics[width=2cm]{images/channel-infobox.png}
\caption{Channel information box}
\label{channel-infobox}
\end{figure}

\subsection{Overlays}

Waveforms may have additional information overlaid on top of them, such as protocol decodes. Each overlay has its own
information box, which may be double-clicked to open the properties dialog and configure it just like any other
channel.

Fig. \ref{overlays} shows
an example of an analog waveform with three overlays: thresholding it to NRZ digital, recovering a sampling
clock with a CDR PLL, and finally decoding the serial NRZ data stream to TMDS protocol data and control events.

\begin{figure}[H]
\centering
\includegraphics[width=14cm]{images/overlays.png}
\caption{Waveform showing two digital overlays and a data decode overlay}
\label{overlays}
\end{figure}

Overlays can be deleted but cannot currently be moved between waveform areas or reordered within a single waveform area
(scopehal-apps:7, scopehal-apps:6)