|
|
|
\chapter{Usage}\label{ch:usage}
|
|
|
|
|
|
|
|
% Maybe this is too much of a guide, but I think a section with the user's
|
|
|
|
% description should be present and there is not much other content to write
|
|
|
|
% here. Also, the UI is currently horrible, so it is worth having this
|
|
|
|
% somewhere, and since there is no documentation, here is the place probably.
|
|
|
|
|
|
|
|
In this chapter we describe the program from the user's point of view and
|
|
|
|
present its features.
|
|
|
|
|
|
|
|
\section{Running Birdvisu}
|
|
|
|
|
|
|
|
First, the user needs to obtain Birdvisu from somewhere. Either, the
|
|
|
|
attachment~\ref{att:birdvisu} can be extracted, or the project can be
|
|
|
|
downloaded from its repository at
|
|
|
|
\url{https://gitea.ledoian.cz/LEdoian/birdvisu}, which will also contain any
|
|
|
|
future improvements.
|
|
|
|
|
|
|
|
The only strict dependency of Birdvisu is Python3.10 or newer. While the project
|
|
|
|
depends on the PySide6 library for the user interface, it can be downloaded
|
|
|
|
as a wheel\X{glos} from PyPI. Of course, using a system-wide installation of
|
|
|
|
PySide6 is also possible.
|
|
|
|
|
|
|
|
Birdvisu can read the topology information from files, so it is not necessary
|
|
|
|
to have a BIRD running and configured if only showing static data is required.
|
|
|
|
|
|
|
|
We only support running the project on Linux. However, Birdvisu might be able
|
|
|
|
to run on other types of operating systems, since we have only used
|
|
|
|
cross-platform libraries.
|
|
|
|
|
|
|
|
There are several ways to start the program. The recommended method is to
|
|
|
|
install the project into a Python virtual environment, but running the
|
|
|
|
\verb|visu.py| script also works when PySide6 is installed in the system.\X{uuuuuuuuuuu!!}
|
|
|
|
|
|
|
|
Once the program is started, the user is presented with an empty canvas. Using
|
|
|
|
the \emph{Topology} menu, it is possible to load both a reference and current
|
|
|
|
topologies. Both can be loaded from a file, the current one can also be
|
|
|
|
retrieved directly from a running BIRD via its socket. In the latter case, the
|
|
|
|
user is provided with a dialog to pick an area and OSPF instance.
|
|
|
|
|
|
|
|
Once both topologies are loaded, the graph of the topolgy appears. Now, the
|
|
|
|
vertices can be moved around to the user's liking. Alternatively, the
|
|
|
|
\emph{Positions} menu provides a way to load the positions of vertices from a file.
|
|
|
|
|
|
|
|
The program expects the topology files to have the \verb|.ospf| extension,
|
|
|
|
positioning files may end in \verb|.visu|. Nevertheless, any files may be used,
|
|
|
|
they just are not offered by default.
|
|
|
|
|
|
|
|
Several highlighting ways are available. In the \emph{Highlight} menu, the user
|
|
|
|
can choose to show differences between the reference and current topology, or
|
|
|
|
set the widths of edges according to their costs. Alternatively, by
|
|
|
|
right-clicking any vertex, it is possible to highlight its shortest path DAG.
|
|
|
|
If the user wants to find a specific route, showing the DAG also serves as
|
|
|
|
selecting the start vertex. The context menus for vertices then allow finding
|
|
|
|
the path to those vertices. Note that stub and external networks are sinks in
|
|
|
|
the OSPF topology, so it is expected that the program draws an empty DAG for them.
|
|
|
|
|
|
|
|
Finally, there is an option to reload the shown graph in the Topology menu. We
|
|
|
|
decided that the graph should not change unexpectedly, because that could be
|
|
|
|
unpleasant to use.
|
|
|
|
|
|
|
|
As a part of Birdvisu we ship the files \verb|gennet.ospf|,
|
|
|
|
\verb|gennet-changed.ospf| and \verb|gennet.visu| for demonstration purposes.
|
|
|
|
These files provide a topology of the default Gennet, the same topology with
|
|
|
|
several manual changes, and a placement of vertices like in figure~\ref{fig:gennet}.
|
|
|
|
|
|
|
|
\iffalse
|
|
|
|
\section{Extending Birdvisu}
|
|
|
|
\fi
|