Walkthrough - GSW 2021

Owned by Will Merges (RIT Student)
Last updated: Dec 12, 2021

System Constraints:

The GSW system is designed be run on x86 architecture with a linux based operating system, some applications may require additional graphical support like an X server to run.

The current operating systems tested to run GSW code are:

Building the code requires the following dependencies:

  • make
  • g++

For using some UI applications (Grafana & InfluxDB), it is required that mDNS is supported. The current system uses the following programs, which are installed by default in Ubuntu 18.x.x:

  • avahi-daemon (expected to started as a service at boot)
  • avahi-publish (used by applications to advertise their address as a certain name, e.g. grafana.local)

The code:

Make sure git is installed on your system.

Download the GSW repository with:

git clone https://github.com/WillMerges/GSW-2021
Run the following commands from the GSW_2021 directory to install (only the first time):
chmod +x install
./install

To get subsequent updates use:

git pull

Note: the URL for the git repository will change once it's migrated to the launch GitHub account (currently having permissions issues).

Building/Running:

All commands run from GSW_2021 directory.

Before building or running, set environment variable(s):

. setenv

Build all GSW software:

make all

Remove all build files:

make clean
To start the GSW system (replace 'current' with a different directory to use an alternate GSW configuration):
./startup/current/start_gsw
To stop the GSW system (replace 'current' with whatever directory you used to start GSW):
./startup/current/shutdown_gsw

To run UI applications see Using the UI - GSW-2021

To run a simulation see Using the Simulation - GSW 2021

Code Walkthrough (all paths are relative to GSW_2021 directory):

  • install - a script used to install the software for the first time. Run this after pulling the git repository for the first time. It sets permissions and some defaults.
  • setenv - a script that sets the GSW_HOME variable (and potentially other variables) of your current shell environment. This script needs to be run before building or running anything. It must be run as '. setenv' and not './setenv' or else the current environments variables will not be updated.
  • include - all C/C++ header files
    • include/common - common header files to all GSW code
    • include/lib - header files for each GSW library
  • lib - source code for GSW libraries. All of these are shared libraries used by processes to carryout common tasks needed by the ground software.
    • lib/dls - data logging system library. This library allows applications to log messages and received telemetry packets to files and system FIFOs.
    • lib/nm - network manager library. This library handles sending and receiving messages to/from the ground station over the network.
    • lib/shm - the shared memory library. This handles simple access to shared memory blocks. Contains the "Shm" class which is widely used.l
    • lib/telemetry - the telemetry library. This uses the "shm" library to control access to shared memory blocks. The "TelemetryShm" object controls locking for reading and writing to shared memory blocks. The "TelemetryViewer" object is the top level object applications should use to access shared memory, it uses a "TelemetryShm" object to access data in shared memory and handles conversion and selecting the most recent data for the user.
    • lib/vcm - vehicle configuration manager library. This library handles reading config files found in data/*/config for each different rocket/payload/vehicle. It allows applications to know the addresses of different measurements in shared memory, their sizes, types, and names as well as network information.
  • proc - all GSW system processes that need to be run/running for any applications to function.
    • proc/decom - decommutation process. This process forks itself for however many different telemetry packets there are.
    • proc/dlp - data logging process. This process handles writing system messages and packets logged using the dls library and physically writes that data to the filesystem.
    • proc/shmctl - shared memory control process. This is a simple process run at startup and shutdown to create and destroy shared memory blocks.
    • proc/reaper - this is the reaper process. It is a strange work around for how blocking on telemetry updates works. Processes are able to block on updates to shared memory, but if the process is killed shared memory will stay locked and lock the whole system. Processes that access shared memory should use the "force_wake" function of the TelemetryViewer object in their signal handlers to wake the process up with this process before killing it. The Reaper process is no longer necessary, it existed due to weird behavior of the futex syscall when a signal is received, a better solution involving remapping the virtual memory that the futex syscall operates on is used instead. See the "TelemetryShm" object for more information. Using the reaper process relied on the fact that the process receiving the signal to terminate will exit it's signal handler before the reaper is able to call futex_wake, if this is not the case the wake will be missed and the process will block and ignore the signal. This appears to be unintended behavior in the Linux kernel and according to the man pages should exit anytime a signal is received while blocked, which does not happen. Regardless, relying on the time of execution was not a robust solution so remapping the futex word was used instead.
    • proc/tool - any tools used to debug, test, or parse data are found here.
      • proc/tool/mqueue_test - sends test messages using the dls library. The test is make sure the dlp process is reading from the MQueue.
      • proc/tool/shmtest - tests shared memory and the shm lib. Builds two executables: write_test and read_test which write and read from shared memory respectively. They expect the config file used for the vcm library to be 4 bytes total measurement(s) size. The script overload.py calls write_test several times to test for issues with multiple writes in a short time period.
      • proc/tool/vcm_test - tests the vcm library for errors.
      • proc/tool/decom_test - tests the decom process by creating a fake UDP server. Run udpserv.py to send messages as the receiver for a rocket would. udpclient.py only exists to test udpserv.py.
      • proc/tool/log2csv - converts log files to a CSV file containing all measurements received over telemetry.
  • app - application level programs. Programs that can be run after the ground station is started that access the data and use various functions of the API created in lib and proc.
    • app/mem_view - memory view, shows the current hex values for all telemetry measurements on standard output.
    • app/val_view - telemetry view, similar to mem_view but shows the converted value of measurements depending on type information from the VCM config file.
    • app/map - Google Earth GPS mapping application
      • app/map/print_gps - this prints GPS measurements to standard output, source file is app/map/print_gps.cpp.
      • app/map/CreateLink.py - creates a KML file containing a network link to the file that will be updated with GPS information. This is the file that should be viewed in Google Earth to see live updates.
      • app/map/GPSTrack.py - takes GPS data from standard input and writes it to a KML file, this is the KML file linked to in the network link.
      • app/map/run.sh - this runs all of the above programs to create a file called "main.kml" that can be viewed in Google Earth to see live GPS updates.
    • app/voice - this is a voice output application. It reads altitude and GPS information and uses text-to-speech to say information about the flight.
    • app/view_log - this views the system logs live and prints messages to standard out.
    • app/sample_processing_app - this is an abandoned UI idea that used the Processing language to show telemetry data.
    • app/db - this contains software to upload telemetry to a database and view it over the browser.
      • app/db/fwd_influx - forward to InfluxDB, this is the program that reads measurements from telemetry and forwards them to an InfluxDB database using the UDP line protocol.
      • app/db/grafana - this contains configuration information and scripts for starting a Grafana server on the machine. Grafana is used to query the InfluxDB server and show telemetry data is a nice UI.
      • app/db/run_influx - this contains configuration information and scripts for starting an InfluxDB server on the machine.
  • log - where system log files are stored.
    • log/clean.sh - cleans all  .log files from the current directory.
    • log/fifo.sh - creates a fifo file at log/system.fifo that is used to read system messages outputted by the dlp process. Another processes can attach to this fifo and read the messages (having multiple processes attach is a current limitation).
    • log/save.sh - saves current *.log files to the directory specified by argument 1.
    • log/system.log[number] - system message log file created by dlp.
    • log/telemetry.log[number] - telemetry data log file created by dlp.
    • log/log.csv - the CSV file generated by "log2csv" from the most recent telemetry data log files.
    • log/system.fifo - a temporary fifo file used to forward system messages from dlp.
  • startup - where startup scripts and temporary files are stored.
    • startup/current - symbolic link to the current startup scripts directory.
    • startup/select_current.sh - provide and argument to a directory that should be the new current startup scripts directory, it will change the symbolic link.
    • startup/default/start_gsw - start ground software in default configuration. Creates the logging fifo file, creates one shared memory segment for the current default vcm config file, starts dlp, and starts decom.
    • startup/default/shutdown_gsw - shutdown processes started by start_gsw.
    • startup/default/start_* - start some aspect of the GSW software. TODO.
    • startup/default/pidlist - temporary file only created when running GSW. DO NOT DELETE, run shutdown_gsw instead and the file will be deleted.
  • data - where configuration data / vehicle or launch specific data is found.
    • data/config - a symbolic link to the current default vcm config file.
    • data/select_config.sh - select the current default vcm file by supplying the name of a directory to look for the config file in.
    • data/[directory name] - configuration information / data for a specific vehicle or launch.