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 \glspl{telescope} 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.
See figure \ref{fig:video-enclosure-mount-tripod}, page \pageref{fig:video-enclosure-mount-tripod}
for a photo of the setup used with KStars below.

The telescope mount will be used in sidereal tracking mode,
where the stars will appear as
``points'', and the \glspl{satellite} will appear as trails.
The mount is not used in a satellite tracking mode.
Sidereal is the ``standard'' tracking mode of \glspl{telescope}.
\index{Sky-Watcher}\index{INDI}\index{Ekos}

KStars is the ``main'' application, but it depends on other key parts.
\gls{INDI} is the protocol that KStars uses for telescope control.
\gls{INDI} itself is a collection of applications.
While KStars has the main sky chart and Ekos is launched within it,
the actual mount control is done with the Ekos application.
While it may sound complex, all of this is set up pretty easily in
\gls{Debian}.

\begin{minted}{sh}
# Quick and dirty from memory, something like:
sudo apt update
sudo apt install kstars indi-bin indi-eqmod indi-gpsd
\end{minted}

KStars has a sky chart, as can be see in figure \ref{fig:kstars-skychart},
page \pageref{fig:kstars-skychart}.
When mount control is functioning, a location on the sky chart, such as a star,
 can be clicked on and the mount will go to that location and optionally track it.
Using this, a telescope mount can be used to easily point the camera at a location
and track it to observe telescopes. It should also provide a superior \gls{FITS} file
for extracting data (XXX made up).
\index{KStars}\index{sky chart}\index{GOTO}\index{mount}\index{track}

\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}


\section{GNSS with \texttt{gpsd}}
\label{sec:software-overview}
\index{GNSS}\index{GPS}\index{Galileo}\index{GLONASS}\index{Beidou}
\index{gpsd}

\gls{GNSS} is used for time synchornization and for (somewhat)
accurately determining the location of the observation.

\gls{GNSS} collectively includes the USA \gls{GPS}, Europe's Galileo,
Russia's GLONASS, and China's Beidou, as well as other
regional systems.
\index{GPS}\index{Galileo}\index{GLONASS}\index{Beidou}

A basic, widely available \gls{COTS} USB \gls{GNSS} device
with a basic (or no!) \gls{antenna} plugged into the embedded
computer can get time and location accurate enough for the
purposes here. See various U-Blox devices, for example.
\index{COTS}\index{USB}\index{U-Blox}

In \gls{Debian} \gls{GNSS} service with a USB device can be provided
by the \texttt{gpsd} application.
\index{Debian}

\begin{minted}{sh}
sudo apt install gpsd gpsd-tools
\end{minted}
\index{gpsd}

Edit the configuration file, \texttt{/etc/default/gpsd} like:

\begin{minted}{sh}
DEVICES="/dev/ttyACM0"
GPSD_OPTIONS="-Gn"
USBAUTO="false"
\end{minted}

This will start a \texttt{gpsd} daemon listening on all interfaces,
so it can be used by other computers on the network (such as if
acquire and process are on different machines). Using the
device \texttt{/dev/ttyACM0} can be problematic if there are multiple
\texttt{/dev/ttyACM*} devices. Perhaps something like this could be
used in that case:

\begin{minted}{sh}
DEVICES="/dev/serial/by-id/usb-u-blox_AG_-_www.u-blox.com_u-blox_GNSS_receiver-if00"
\end{minted}

Even with \texttt{gpsd} configuration listening on all IPs,
don't think \texttt{systemd} won't do what it likes. So
you may have to do:

\begin{minted}{sh}
systemctl edit --full gpsd.socket
\end{minted}

And create a configuration like this (I have IPv6 disabled, in this case):

\begin{minted}{sh}
[Unit]
Description=GPS (Global Positioning System) Daemon Sockets

[Socket]
ListenStream=/run/gpsd.sock
# ListenStream=[::]:2947
ListenStream=0.0.0.0:2947
SocketMode=0600
BindIPv6Only=no

[Install]
WantedBy=sockets.target
\end{minted}

(Re)start:

\begin{minted}{sh}
sudo systemctl restart gpsd.service gpsd.socket
\end{minted}

Test all is good:

\begin{minted}{sh}
gpsmon -n
# or
cgps -u m
\end{minted}
\index{gpsmon}\index{cgps}

Enable to start on boot:

\begin{minted}{sh}
sudo systemctl enable gpsd.service gpsd.socket
\end{minted}

See below for sample output from \texttt{cgps}.

\begin{minted}{sh}
┌───────────────────────────────────────────┐┌──────────────────Seen 39/Used 28┐
│ Time:        2022-09-02T00:40:28.000Z (18)││GNSS   PRN  Elev   Azim   SNR Use│
│ Latitude:         40.56896250 N           ││GP  1    1  24.0  237.0  44.0  Y │
│ Longitude:       105.22600420 W           ││GP  3    3  63.0  297.0  50.0  Y │
│ Alt (HAE, MSL):   1848.352,   1869.637 m  ││GP  4    4  33.0  292.0  45.0  Y │
│ Speed:             0.05 km/h              ││GP 16   16  21.0  162.0  36.0  Y │
│ Track (true, var):    85.1,   8.2     deg ││GP 21   21  13.0  218.0  40.0  Y │
│ Climb:             0.00 m/min             ││GP 22   22  40.0   77.0  18.0  Y │
│ Status:         3D DGPS FIX (29 secs)     ││GP 26   26  43.0  140.0  46.0  Y │
│ Long Err  (XDOP, EPX):  0.40, +/-  1.5 m  ││GP 31   31  57.0   49.0  39.0  Y │
│ Lat Err   (YDOP, EPY):  0.36, +/-  1.3 m  ││SB131   44  42.0  198.0  44.0  Y │
│ Alt Err   (VDOP, EPV):  0.90, +/-  0.7 m  ││SB133   46  37.0  214.0  41.0  Y │
│ 2D Err    (HDOP, CEP):  0.51, +/-  0.5 m  ││GL  6   70  48.0   99.0  21.0  Y │
│ 3D Err    (PDOP, SEP):  1.04, +/-  5.1 m  ││GL  7   71  62.0  352.0  51.0  Y │
│ Time Err  (TDOP):       0.57              ││GL  8   72  19.0  314.0  47.0  Y │
│ Geo Err   (GDOP):       1.18              ││GL  9   73  71.0  149.0  45.0  Y │
│ ECEF X, VX:   -1274598.340 m   -0.010 m/s ││GL 10   74  28.0  194.0  29.0  Y │
│ ECEF Y, VY:   -4682900.030 m   -0.010 m/s ││GL 23   87  13.0  305.0  48.0  Y │
│ ECEF Z, VZ:    4127382.070 m    0.020 m/s ││GA  2  302  31.0  168.0  40.0  Y │
│ Speed Err (EPS):       +/-  0.4 km/h      ││GA  3  303  72.0   40.0  39.0  Y │
│ Track Err (EPD):        n/a               ││GA  8  308  40.0  300.0  47.0  Y │
│ Time offset:           -0.005160195 s     ││GA 13  313  22.0  285.0  43.0  Y │
│ Grid Square:            DN70jn26          ││GA 15  315  17.0  232.0  43.0  Y │
└───────────────────────────────────────────┘└More...──────────────────────────┘
\end{minted}
\index{cgps}