update configuration documentation

README.md

@@ -5,15 +5,44 @@
 [![license](https://img.shields.io/github/license/umdbpp/packetraven)](https://opensource.org/licenses/MIT)
 
 PacketRaven is a command-line dashboard that retrieves location telemetry sent by high-altitude balloon payloads.
-
+The program is designed to be run during a flight and display information in a terminal user interface (TUI):
 ![demo](https://media.githubusercontent.com/media/UMDBPP/PacketRaven/main/docs/images/demo.gif)
 
-To install PacketRaven, download an executable from the [latest release](https://github.com/UMDBPP/PacketRaven/releases)
-and run it from the terminal with a 
-[configuration file](https://packetraven.readthedocs.io/en/latest/configuration.html):
+## Features
+
+- retrieve location telemetry from a variety of sources, including
+  - https://amateur.sondehub.org
+  - https://aprs.fi
+  - a TNC-equipped radio connected via USB
+  - a text file containing raw APRS frames
+  - a GeoJSON file with telemetry attached to coordinates
+- retrieve balloon flight predictions from https://predict.sondehub.org
+- plot variables such as altitude and ascent rate over time
+- estimate landing time and location
+
+## Installation
+
+[Download an executable file from the latest release.](https://github.com/UMDBPP/PacketRaven/releases)
+
+> **Note**
+> Alternatively, you may compile the program yourself:
+> ```shell
+> git clone https://github.com/UMDBPP/PacketRaven.git
+> cd packetraven
+> cargo build --release
+> ls target/release
+> ```
+
+## Usage
+
+First, you need a configuration file. You may use one from the `examples/` directory in this repository, or [write one yourself](https://packetraven.readthedocs.io/en/latest/configuration.html).
+
+Then, run your executable from the terminal with the path to your configuration as the first argument:
 ```shell
 ./packetraven_Windows.exe examples/example_1.yaml
 ```
+
+You should then see the following in your terminal window:
 ![starting screen](https://media.githubusercontent.com/media/UMDBPP/PacketRaven/main/docs/images/example1_log.png)
 
 The left and right arrow keys (or `Tab` and `Shift+Tab`) cycle through active tabs, 
@@ -22,11 +51,3 @@ and the up and down arrow keys change the current plot (or scroll through log me
 
 To quit, press `q` or `Esc`.
 
-> **Note**
-> Alternatively, you may build the executable from source with Cargo:
-> ```shell
-> git clone https://github.com/UMDBPP/PacketRaven.git
-> cd packetraven
-> cargo build --release
-> ls target/release
-> ```

docs/rtd_environment.yaml

@@ -5,3 +5,4 @@ dependencies:
   - python
   - sphinx
   - sphinx-mdinclude
+  - sphinx_rtd_theme

docs/source/configuration.rst

@@ -1,23 +1,45 @@
-configuration
-=============
+Configuration File
+##################
 
-The configuration file is in YAML format. All units are metric (``m``, ``m/s``, ``C``, etc.).
+The configuration file is in YAML format. All units are metric (meters, seconds, meters per second).
 
-``callsigns``
--------------
+.. literalinclude:: ../../examples/example_3.yaml
+   :language: yaml
 
-a list of callsigns as strings, including SSIDs if present
+More examples can be found at the :doc:`examples` page.
+
+.. _callsigns:
+
+Callsigns (``callsigns``, optional)
+===================================
+
+a list of callsigns as strings, including SSIDs
 
 .. code-block:: yaml
 
    callsigns:
-     - KC3SKW-8
      - KC3SKW-9
+     - KC3ZRB
+
+if present, only telemetry with callsigns in this list will be displayed
+
+Time (``time``, optional)
+=========================
+
+``start`` and ``end`` (optional)
+--------------------------------
 
-``connections``
----------------
+start and end times by which to filter received telemetry, as either ``yyyy-mm-dd`` or ``yyyy-mm-dd HH:MM:SS``
 
-connections from which to retrieve packets
+``interval`` (default ``60``)
+-----------------------------
+
+frequency in seconds that PacketRaven will fetch new telemetry
+
+Connections (``connections``)
+=============================
+
+connections from which to retrieve telemetry
 
 .. code-block:: yaml
 
@@ -34,8 +56,8 @@ connections from which to retrieve packets
    To define a connection with no options (i.e. the ``sondehub`` entry, above), use YAML's empty flow mapping syntax ``sondehub: {}``.
    The empty block mapping syntax (``sondehub: ``) is equivalent to ``sondehub: null`` and will not initiate the connection.
 
-``text``
-^^^^^^^^
+Text connection (``text``)
+--------------------------
 
 text entries can be
 
@@ -56,32 +78,70 @@ text entries can be
     - port: COM3
       baud_rate: 9600
 
-.. note::
-  File connections use the ``path:`` entry, while 
-  serial port connections use the ``port:`` and ``baud_rate:`` entries instead.
+File 
+^^^^
 
-``sondehub``
-^^^^^^^^^^^^
+``path``
+""""""""
 
-.. code-block:: yaml
+path to a file (can be a URL)
+
+``callsigns`` (optional)
+""""""""""""""""""""""""
+
+see the :ref:`Callsigns <callsigns>` section
+
+Serial
+^^^^^^
+
+``port``
+""""""""
+
+serial port to connect to, i.e. `COM4` or `/dev/ttyUSB1`
+
+``baud_rate``
+"""""""""""""
+
+baud rate with which to connect to serial port
+
+``callsigns`` (optional)
+""""""""""""""""""""""""
+
+see the :ref:`Callsigns <callsigns>` section
 
-  sondehub:
-    callsigns: 
-      - KC3SKW-8
+SondeHub connection (``sondehub``)
+----------------------------------
 
-``aprs_fi``
+if present, query the database at https://amateur.sondehub.org for telemetry from the given callsigns
+
+``callsigns`` (optional if already defined globally)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+see the :ref:`Callsigns <callsigns>` section
+
+APRSfi Connection (``aprs_fi``)
+-------------------------------
+
+if present, query the database at https://aprs.fi for telemetry from the given callsigns
+
+``api_key``
 ^^^^^^^^^^^
 
-.. code-block:: yaml
+get an API key from https://aprs.fi/page/api
 
-  aprs_fi:
-    api_key: 123456.abcdefhijklmnop
+``callsigns`` (optional if already defined globally)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``postgres``
-^^^^^^^^^^^^
+see the :ref:`Callsigns <callsigns>` section
+
+PostGres Database connection (``postgres``, requires the ``postgres`` feature)
+------------------------------------------------------------------------------
 
 .. warning::
-   requires the ``postgres`` feature
+   requires compiling with the ``postgres`` feature:
+   ..code-block:: shell
+
+     cargo build --release --features postgres
 
 .. code-block:: yaml
 
@@ -98,39 +158,10 @@ text entries can be
     username: "ssh_user1"
     password: "ssh_password1"
 
-``time``
---------
-
-.. code-block:: yaml
-
-   time:
-     start: 2022-03-05 00:00:00
-     end: 2022-03-06 00:00:00
-     interval: 120
-   
-``start`` and ``end``
-^^^^^^^^^^^^^^^^^^^^^
-
-start and end times by which to filter received telemetry
-
-``interval``
-^^^^^^^^^^^^
-
-interval in seconds after which to fetch new telemetry
-
-``output_file``
----------------
-
-GeoJSON file to output telemetry to
-
-.. code-block:: yaml
-
-   output_file: example_3.geojson
+Flight Prediction (``prediction``, optional)
+============================================
 
-``prediction``
---------------
-
-default prediction profile that will be applied to all callsigns
+query parameters for https://predict.sondehub.org
 
 .. code-block:: yaml
 
@@ -144,14 +175,103 @@ default prediction profile that will be applied to all callsigns
       ascent_rate: 6.5
       burst_altitude: 25000
       sea_level_descent_rate: 9
-    float:
-      duration: 3600
-      float_altitude: 25000
-      uncertainty: 500
     output_file: example_3_prediction.geojson
 
+Launch / starting location and time (``start``)
+-----------------------------------------------
+
+.. code-block:: yaml
+
+  start:
+    coord:
+      x: -78.4987
+      y: 40.0157
+    time: 2022-03-05 10:36:00
+
+``coord``
+^^^^^^^^^
+
+``x`` and ``y`` in WGS84 coordinates
+
+``altitude`` (optional)
+^^^^^^^^^^^^^^^^^^^^^^^
+
+altitude in meters
+
+``time``
+^^^^^^^^
+
+time of prediction start, as ``yyyy-mm-dd`` or ``yyyy-mm-dd HH:MM:SS``
+
+Standard Profile (``profile``)
+------------------------------
+
+.. code-block:: yaml
+
+  profile:
+    ascent_rate: 6.5
+    burst_altitude: 25000
+    sea_level_descent_rate: 9
+
 .. note::
    During a flight, the prediction profile for each track will differ from this default configuration; 
    for instance, on ascent the profile will use the actual ascent rate from telemetry, 
    and during descent the prediction will only include the descent stage.
 
+``ascent_rate``
+^^^^^^^^^^^^^^^
+
+expected average ascent rate of the balloon
+
+``burst_altitude``
+^^^^^^^^^^^^^^^^^^
+
+expected burst altitude
+
+``sea_level_descent_rate``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+expected descent rate of the balloon at sea level
+
+Float Profile (``float``, optional)
+-----------------------------------
+
+.. code-block:: yaml
+
+  float:
+    duration: 3600
+    altitude: 25000
+    uncertainty: 500
+
+``duration``
+^^^^^^^^^^^^
+
+expected duration of the float
+
+``altitude``
+^^^^^^^^^^^^
+
+expected altitude of the float
+
+``uncertainty`` (default ``500``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+leeway that the balloon can be considered "at float altitude"
+
+Prediction Output File (``output_file``, optional)
+--------------------------------------------------
+
+path to a GeoJSON file to which to output a predicted flight path
+
+.. code-block:: yaml
+
+  output_file: example_3_prediction.geojson
+
+Telemetry Output File (``output_file``, optional)
+=================================================
+
+path to a GeoJSON file to which to output received telemetry
+
+.. code-block:: yaml
+
+  output_file: example_3.geojson

docs/source/examples.rst

@@ -1,5 +1,7 @@
-examples
-========
+Configuration Examples
+======================
+
+To run these examples, see `the Usage section <https://packetraven.readthedocs.io/en/latest/index.html#usage>`_.
 
 ``examples/example_1.yaml``
 ---------------------------

examples/example_3.yaml

@@ -8,8 +8,6 @@ time:
   end: 2022-03-06 00:00:00
   interval: 120
 
-output_file: example_3.geojson
-
 connections:
   sondehub: {}
   text:
@@ -28,3 +26,5 @@ prediction:
     burst_altitude: 25000
     sea_level_descent_rate: 9
   output_file: example_3_prediction.geojson
+
+output_file: example_3.geojson