SNOUG/src/Software.tex

%
% Software.tex
%
% SatNOGS Optical Unofficial Guide
%
% Copyright (C) 2022, Jeff Moe
%
% This document is licensed under the Creative Commons Attribution 4.0
% International Public License (CC BY-SA 4.0) by Jeff Moe.
%

\section{Software Overview}
\label{sec:software-overview}
\index{software}

See \ref{fig:operation}, page \pageref{fig:operation}
for a diagram with an overview of the software process.

\begin{center}
        \begin{figure}[h!]
% XXX diagram is too large for frame
%	\begin{framed}
                \smartdiagramset{border color=none,
                        uniform color list=jebba-light-blue!60 for 4 items,
                        module x sep=3.75,
                        back arrow distance=0.75,
                }
                \smartdiagram[flow diagram:horizontal]{Acquire, Process, Analyze, Upload}
                \caption{SatNOGS Optical Operation Pipeline}
                \label{fig:operation}
                \index{operation}
%	\end{framed}
        \end{figure}
\end{center}

\section{Setup Optical Ground Station Software}
\label{sec:software-setup}
\index{software}
HOWTO set up and configure a \gls{SatNOGS-Optical} \gls{ground-station}.

Setup an embedded computer, such as an Odroid N2, with \gls{Debian} stable
(11/Bullseye) or testing (Bookworm).
\index{embedded computer}\index{Odroid}\index{Debian}

See each repository for latest documentation.

Install dependencies from \gls{Debian} repository:

\begin{minted}{sh}
sudo apt update
sudo apt install python3-virtualenv python3-pip python3-dev \
    source-extractor astrometry.net \
    libeigen3-dev giza-dev libx11-dev \
    astrometry-data-tycho2 astrometry-data-tycho2-07 \
    astrometry-data-tycho2-08 astrometry-data-tycho2-09 \
    astrometry-data-tycho2-10-19
\end{minted}

Next, install the \texttt{\gls{hough3d-code}} dependency.
\index{hough3d-code}

\begin{minted}{sh}
git clone https://gitlab.com/pierros/hough3d-code
cd hough3d-code
make all
sudo cp -p hough3dlines /usr/local/bin/hough3dlines
\end{minted}

Install \texttt{\gls{satpredict}} from using either the cbassa or spacecruft repo.
\index{satpredict}

\begin{minted}{sh}
cd ../
git clone https://spacecruft.org/spacecruft/satpredict
# Or
#git clone https://github.com/cbassa/satpredict
cd satpredict/
make
sudo make install
\end{minted}

Now install \texttt{stvid}, the main acquisition and processing
application. It is written in \gls{Python}. Either use the spacecruft
\texttt{git} repository or the cbassa one.
\index{stvid}\index{Python}

\begin{minted}{sh}
cd ../
git clone https://spacecruft.org/spacecruft/stvid
# Or use upstream:
#git clone https://github.com/cbassa/stvid
\end{minted}

Optionally, set up a \gls{Python} virtual environment:
\index{Python}\index{virtualenv}

\begin{minted}{sh}
cd stvid
virtualenv -p python3 env
source env/bin/activate
pip install --upgrade pip
\end{minted}

Install dependencies. Numpy needs to be installed first, or the
install fails.

\begin{minted}{sh}
pip install --upgrade numpy
pip install --upgrade -r requirements.txt
\end{minted}
\index{numpy}

If the system \texttt{python3-numpy} conflicts, you could try installing
numpy in the virtualenv thusly:

\begin{minted}{sh}
pip install --upgrade --ignore-installed numpy
\end{minted}

\gls{Debian} in bug \texttt{\#941466} changed the name of the
\texttt{sextractor} dependency to \texttt{source-extractor},
so a symlink is needed for now:
\index{Debian}\index{Source Extractor}

\begin{minted}{sh}
sudo ln -s /usr/bin/source-extractor /usr/local/bin/sextractor
\end{minted}

\section{Configure Software}
\label{sec:software-configure}
Configure the embedded computer.

\begin{minted}{sh}
cd stvid/
cp -p configuration.ini-dist configuration.ini
# Edit
# Note for fields st-username and st-password, *don't* use quotes.
# Set:
vi configuration.ini
\end{minted}
\index{stvid}\index{configuration.ini}

Edit various \texttt{configuration.ini} fields:
\begin{minted}{sh}
# For example:
observer_cospar = 9999        # COSPAR number of observer's site
observer_name = Jeff Moe      # Name of observer
observer_lat = 40.568912      # Latitude of location in decimal degrees
observer_lon = -105.225852    # Longitude of location in decimal degrees
observer_height = 1860         # Elevation of location in meters

observations_path = ./data/obs # Path for raw acquisitions
tle_path = ./data/tle          # Path where TLEs are stored (and updated)
results_path = ./data/results   # Path for results of processed obs

st-username = foo
st-password = bar

# Path to source-extractor
sex_config = /usr/share/source-extractor/default.sex
\end{minted}

Store downloads here:

\begin{minted}{sh}
mkdir -p ./data/obs ./data/tle ./data/results
\end{minted}

The \texttt{ST\_DATADIR} variable is still used, from \texttt{sattools}.
Maybe set all these in \texttt{\~/.bashrc} (suit to fit directory setup):
\index{bashrc}

\begin{minted}{sh}
export ST_DATADIR=$HOME/sattools
export ST_TLEDIR=$HOME/TLE
export ST_OBSDIR=$HOME/satobs
export ST_LOGIN="identity=foo@no:pass"
\end{minted}
\index{sattools}\index{TLE}

Set \texttt{astrometry.net} to run in parallel, assuming you have enough RAM:
(This doesn't appear to work? Breaks?).
\index{astrometry.net}

\begin{minted}{sh}
sudo vim /etc/astrometry.cfg
# Uncomment:
inparallel
\end{minted}


\section{skymap}
\label{sec:skymap}
\index{skymap}\index{orbit}\index{sattools}

Use \gls{skymap} for viewing \gls{satellite} \glspl{orbit} tracks
projected on a map of of the sky. Skymap is part of \gls{sattools}.
\Gls{skymap} isn't a required part of the toolchain, but it is useful
to see what \glspl{satellite} are visibile at a particular time and
location.

Source:

* \url{https://github.com/cbassa/sattools}

My fork:

* \url{https://spacecruft.org/spacecruft/sattools}

\begin{sidewaysfigure}[p!]
        \begin{center}
                \includegraphics[keepaspectratio=true,height=1.00\textheight,width=1.00\textwidth,angle=0]{skymap-giza-21.png}
                \caption{\texttt{skymap} example screenshot.}
                \index{skymap}\index{sattools}
                \label{fig:skymap-giza-21}
        \end{center}
\end{sidewaysfigure}

\fbox{
        \parbox{\linewidth}{
                \textcolor{red}{NOTICE:} \\
                The main upstream sattools package requires non-\gls{libre} \texttt{pgplot} on host computer which is not \gls{DFSG} compatible.
                \index{proprietary}\index{DFSG}\index{pgplot}
        }
}


Described below is how to build and install my fork of \gls{sattools} to use
\gls{skymap} instead of upstream. Upstream requires non-libre software which
also happens to be very difficult for most users to compile. My fork uses the
Giza library which replaces pgplot. It is much easier to build.
\index{fork}\index{sattools}\index{skymap}\index{Giza}

\begin{minted}{sh}
# Install dependencies
sudo apt install giza-dev git make dos2unix source-extractor wcslib-dev \
     libgsl-dev gfortran libpng-dev libx11-dev libjpeg-dev libexif-dev

# Clone repo
git clone https://spacecruft.org/spacecruft/sattools
# Or use upstream (needs more steps)
git clone https://gitub.com/cbassa/sattools

cd sattools/
# Build
make

# Install
sudo make install

# Clean
make clean

# To rebuild
make clean
make

# To uninstall
sudo make uninstall
\end{minted}

See below for \gls{skymap} (fork) usage:
\index{TLE}

\begin{minted}{sh}
tleupdate

# set config in ~/.bashrc XXX

skymap --help
Usage: skymap [OPTION]
Visualize satellites on a map of the sky.

-t, --time    Date/time (yyyy-mm-ddThh:mm:ss.sss) [default: now]
-c, --catalog    TLE catalog file [default: satnogs.tle]
-i, --id    Satellite ID (NORAD) [default: all]
-R, --ra    R.A. [hh:mm:ss.sss]
-D, --decl    Decl. [+dd:mm:ss.ss]
-A, --azimuth    Azimuth (deg)
-E, --elevation    Elevation (deg)
-w, --width    Screen width (default: 1024). Set height too.
-g, --height    Screen height (default: 768). Set width too.
-n, --nmax    nmax line resolution/speed (default 128)
-S, --all-night    All night
-Q, --no-stars    No stars
-a, --all-objects    Show all objects from catalog (default: LEO)
-h, --help    This help
-s, --site    Site (COSPAR)
-d, --iod    IOD observations
-l, --length    Trail length [default: 60s]
-P, --planar-id    planar search satellite ID
-r, --planar-alt    planar search altitude
-V, --visibility-alt    altitude for visibility contours
-p, --positions-file    File with xyz positions
-L, --longitude    manual site longitude (deg)
-B, --latitude    manual site latitude (deg)
-H, --elevation    manual site elevation (m)
\end{minted}


\section{Tracking Software}
\label{sec:software-tracking}
\index{track}\index{software}
The tracking software used depends upon the tracking mount.

See section \ref{sec:hardware-tracking-ground-station},
page \pageref{sec:hardware-tracking-ground-station}
for discussion of hardware tracking mounts.

For our uses here, there are three broad categories of tracking
software:

\begin{mdframed}[backgroundcolor=blue!10,linecolor=blue!30]
\begin{description}
        \item [Telescope] --- Controlling \glspl{telescope} remotely.
        \item [Antenna] --- Controlling \glspl{antenna} remotely with hamlib.
        \item [Cameras] --- Controlling PTZ cameras remotely.
\end{description}
\end{mdframed}
\index{telescope}\index{antenna}


\subsection{Telescope Tracking Software}
Software that can be used with telescope tracking mounts:

\begin{mdframed}[backgroundcolor=blue!10,linecolor=blue!30]
\begin{description}
        \item [INDI] --- Main client/server used by other applications.
        \item [KStars] --- Sky charts, INDI control.
	\item [Ekos] --- Application used within KStars for remote control
         of telescopes and related hardware via \gls{INDI}.
        \item [Stellarium] --- Sky charts, has \gls{INDI} plugin.
	\item [Other INDI] --- Many more applications work with \gls{INDI}.
	\item [INDIGO] --- Positions itself as a next-generation INDI (?).
\end{description}
\end{mdframed}
\index{telescope}\index{INDI}\index{KStars}\index{Ekos}\index{Stellarium}
\index{INDIGO}

Using \gls{INDI} with KStars and Ekos on a Sky-Watcher or Celestron
telescope mount is a known working solution.
\index{Sky-Watcher}\index{Celestron}


\subsection{Antenna Tracking Software}
At present, for the \gls{SatNOGS} network \gls{RF} \glspl{ground-station},
hamlib is typically used for tracking, if directional \glspl{antenna} are
used. Hamlib was originally created for amateur radio equipment, but has
expanded to control many more devices.
\index{hamlib}\index{antenna}\index{RF}\index{amateur radio}

\begin{mdframed}[backgroundcolor=blue!10,linecolor=blue!30]
\begin{description}
	\item [hamlib] --- \Gls{antenna} \gls{rotator} control.
\end{description}
\end{mdframed}

I don't know of anyone prototying a satellite tracking mount with hamlib,
but it should be possible using the ``leap frog'' method, perhaps on the
same mount as existing \gls{SatNOGS} \glspl{antenna}. The mount may not
be steady enough.


\subsection{Camera Tracking Software}
There are applications for using PTZ control of cameras, such as used in
``security'' cameras.

\begin{mdframed}[backgroundcolor=blue!10,linecolor=blue!30]
\begin{description}
	\item [motion] --- PTZ camera control. XXX check
\end{description}
\end{mdframed}

I don't know of any of these being used in satellite tracking prototypes
at present.

\section{KStars}
\label{sec:software-overview}
\index{software}\index{KStars}\index{Debian}
KStars is an application that has been used for years in the astronomy
community. It is well established, well supported and included in \gls{Debian}.

KStars has multiple uses for imaging \glspl{satellite}.
One main use is to control a telescope tracking mount, such as the
hardware described in section \ref{sec:hardware-mounts}, page \pageref{sec:hardware-mounts}.

For the purposes here, described below will be using KStars with a
Sky-Watcher tracking mount with INDI and Ekos.
It will be used in sidereal tracking mode, where the stars will appear as
``points'', and the \glspl{satellite} will appear as trails.
\index{Sky-Watcher}\index{INDI}\index{Ekos}

\begin{sidewaysfigure}[p!]
        \begin{center}
                \includegraphics[keepaspectratio=true,height=1.00\textheight,width=1.00\textwidth,angle=0]{kstars-skychart.png}
                \caption{KStars sky chart, example screenshot.}
                \index{KStars}\index{sky chart}
                \label{fig:kstars-skychart}
        \end{center}
\end{sidewaysfigure}

\begin{sidewaysfigure}[p!]
        \begin{center}
                \includegraphics[keepaspectratio=true,height=1.00\textheight,width=1.00\textwidth,angle=0]{kstars-profile-edit-v4l2.png}
                \caption{KStars using V4L2, example screenshot.}
                \index{KStars}\index{V4L2}
                \label{fig:kstars-profile-edit-v4l2}
        \end{center}
\end{sidewaysfigure}

\begin{sidewaysfigure}[p!]
        \begin{center}
                \includegraphics[keepaspectratio=true,height=1.00\textheight,width=1.00\textwidth,angle=0]{kstars-profile-edit-simulator.png}
                \caption{KStars using simulated CCD, example screenshot.}
                \index{KStars}\index{CCD}
                \label{fig:kstars-profile-edit-simulator}
        \end{center}
\end{sidewaysfigure}