From 740c7e940283cd3a4e1453c09f2251f0b6ca954c Mon Sep 17 00:00:00 2001 From: zacharyburnett Date: Wed, 7 Jun 2023 10:32:21 -0400 Subject: [PATCH] update configuration documentation --- README.md | 45 ++++-- docs/rtd_environment.yaml | 1 + docs/source/configuration.rst | 248 +++++++++++++++++++++++++--------- docs/source/examples.rst | 6 +- examples/example_3.yaml | 4 +- 5 files changed, 224 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index a72585b9..9db5dbae 100644 --- a/README.md +++ b/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 -> ``` diff --git a/docs/rtd_environment.yaml b/docs/rtd_environment.yaml index bb4810ec..6289bebe 100644 --- a/docs/rtd_environment.yaml +++ b/docs/rtd_environment.yaml @@ -5,3 +5,4 @@ dependencies: - python - sphinx - sphinx-mdinclude + - sphinx_rtd_theme diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 4ce451ca..3909d1dd 100644 --- a/docs/source/configuration.rst +++ b/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 ` 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 ` 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 ` 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 ` 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 diff --git a/docs/source/examples.rst b/docs/source/examples.rst index 9d15095c..fa149fda 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -1,5 +1,7 @@ -examples -======== +Configuration Examples +====================== + +To run these examples, see `the Usage section `_. ``examples/example_1.yaml`` --------------------------- diff --git a/examples/example_3.yaml b/examples/example_3.yaml index 5fe9fa01..ddc173f0 100644 --- a/examples/example_3.yaml +++ b/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