Skip to content

Commit

Permalink
update configuration documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
zacharyburnett committed Jun 7, 2023
1 parent 76258ef commit 740c7e9
Show file tree
Hide file tree
Showing 5 changed files with 224 additions and 80 deletions.
45 changes: 33 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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
> ```
1 change: 1 addition & 0 deletions docs/rtd_environment.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@ dependencies:
- python
- sphinx
- sphinx-mdinclude
- sphinx_rtd_theme
248 changes: 184 additions & 64 deletions docs/source/configuration.rst
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
6 changes: 4 additions & 2 deletions docs/source/examples.rst
Original file line number Diff line number Diff line change
@@ -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``
---------------------------
Expand Down
4 changes: 2 additions & 2 deletions examples/example_3.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ time:
end: 2022-03-06 00:00:00
interval: 120

output_file: example_3.geojson

connections:
sondehub: {}
text:
Expand All @@ -28,3 +26,5 @@ prediction:
burst_altitude: 25000
sea_level_descent_rate: 9
output_file: example_3_prediction.geojson

output_file: example_3.geojson

0 comments on commit 740c7e9

Please sign in to comment.