<commit_before>:toc: right
:icons: font

= Introduction to MapView

link:https://github.com/noexc/mapview[MapView] is an on-the-ground telemetry
reception system for
link:https://en.wikipedia.org/wiki/High-altitude_balloon[high-altitude balloon projects].
It is meant to be used by those with an interest in HAB chases, as a means of
tracking and following the balloon during a flight.

It consists of several individual components, some of which interoperate with
each other, and some of which can be run independently during and after a
balloon chase.

MapView is written from a standpoint that prefers stability (and correctness)
and modularity over speed and ease of installation. Because of this, setting it
up for the first time can be daunting, particularly if you are not familiar with
building and installing Haskell packages.

It is our hope that this documentation makes the process as pain-free as
possible, but we invite and encourage questions about the process in the
link:irc://irc.freenode.net/noexc[#noexc channel on freenode].

== History

MapView began its life as a project for the University of Akron Amateur Radio
club's "HABP-*n*" series of balloon flights. These flights were conducted yearly
and there was a need for an effective and easy way to track the balloon.

<NAME>, N8SQL, wrote a prototype of the project in NodeJS as an experiment,
having never coded in NodeJS. The prototype got positive feedback, but Ricky
ended up realizing that NodeJS would not be a viable platform to meet the goals
of the project. A rewrite in Haskell was started on
link:https://github.com/noexc/mapview/commit/3df37823aa9bf596406cc5dbdeed004d5a167517[January 20, 2014]
and has been in active development ever since.

Alumni and former students of the University of Akron formed a new club, the
link:https://noexc.org/[Northeast Ohio Experimenters Club], and maintenance
of MapView and related projects has continued under that name. The project
continues to be led by <NAME> as new NOEXC flights incorporate new and
interesting requirements. MapView is and always will be free and open source
software and we welcome and encourage questions, contributions, and comments.

== Components

MapView is built in a particularly modular way as
link:http://noexc.org/[our own] requirements change fairly often. Typically, we
experiment with new technologies and telemetry systems on each flight we
perform, and it is important that we are able to compensate for these changes
quickly, and reflect them in the MapView codebase with relative ease.

Here we give a brief overview of each component. Each component has its own
documentation file with more information about the role it plays.

Programs (each of which is considered an individual component) which ship with
MapView, as a rule, are all prefixed with `mapview-`. For example,
`mapview-telemetryparser` is the program (component) which parses raw telemetry
in realtime during a flight.

We don't currently make use of any kind of real "IPC" framework. Instead, we
write out state to files (usually in JSON) and listen for changes to these files
in various components. In the future, we could optionally make use of something
along the lines of `dbus` for dealing with IPC, if there is a need/want.

=== mapview: The Library

TIP: We also publish link:/haddock[haddock] documentation for this
library.

There is a common library used by all components. This includes, for example,
pieces of code for handling
link:https://en.wikipedia.org/wiki/Cyclic_redundancy_check[CRC] validation,
parsing of raw telemetry data, configuration file parsing, and datatypes and
typeclasses which are reused throughout the various components.

=== `mapview-telemetryparser` [link:mapview-telemetryparser{ext-relative}[main]]

`mapview-telemetryparser` is the program which parses raw telemetry data during
a flight. In short, it shells out to some modem (`minimodem` by default. See the
link:Configuration{ext-relative}[Configuration] documentation for details) and
parses anything that the modem sends to `STDOUT`. If the parse is successful --
that is, if we receive a valid packet from the HAB telemetry which passes the
CRC check -- it writes out a JSON representation of this packet to the file
specified in `mapview.conf`. If the parse fails, it writes the error to the
terminal, with a short description of why (provided by the
link:https://hackage.haskell.org/package/trifecta[Trifecta] library).

`mapview-telemetryparser` also saves a raw log of the modem output, for later
processing. We use this, for example, in `mapview-generate-charts` for making
graphs of flight data post-factum.

Lastly, `mapview-telemetryparser` writes a third file which is a list of all
coordinates obtained from the balloon thus far. It does this by reading the file
and prepending the latest successfully parsed set of coordinates to it, then
writing the result. We do this so that when one refreshes any of the map viewing
interfaces (such as `mapview-psc`), they are able to see a trail of where the
balloon has been.

=== mapview-send

`mapview-send` listens for changes to the files updated by
`mapview-telemetryparser` and sends appropriate updates to all clients who are
viewing a frontend. That is, a frontend implementation must connect (via
websockets) to a server that `mapview-send` starts. When `mapview-send` detects
changes to relevant files, it puts them into a format that frontend clients can
understand. The frontend can then update its view based on this information.

=== mapview-generate-charts [link:mapview-generate-charts{ext-relative}[main]]

`mapview-generate-charts` is usually used post-factum. When a flight completes,
`mapview-generate-charts` will re-run the raw telemetry log and parse it again,
graphing certain things such as altitude and temperature.

=== mapview-psc

Our official frontend is maintained in a
link:https://github.com/noexc/mapview-psc[separate repository] from MapView
itself, though changes in one repository and sometimes require changes in the
other.

It is written in link:http://purescript.org[PureScript], a strongly typed
programming language which compiles down to JavaScript.

mapview-psc can be considered a "reference frontend," if you will. The frontend
is one of the simplest parts of MapView, and those with specific needs could
easily write their own, so long as it can connect to the `mapview-send`
websockets server.

== Bugs, Comments, Issues

Please, please, **please** report any bugs or issues to our GitHub repositories
(mapview for the backend, mapview-psc for the frontend). We cannot fix or
discuss issues unless we know that you are having them!

General comments and questions can (and should! We don't bite!) be asked on our<commit_msg>Start on new docs...not really<commit_after>:toc: right
:icons: font

= Introduction to MapView

link:https://github.com/noexc/mapview[MapView] is an on-the-ground telemetry
reception system for
link:https://en.wikipedia.org/wiki/High-altitude_balloon[high-altitude balloon projects].
It is meant to be used by those with an interest in HAB chases, as a means of
tracking and following the balloon during a flight, as well as allowing for
both real-time and retroactive analysis over telemetry data received during the
course of a flight.

MapView is written from a standpoint that prefers stability (and correctness)
and modularity over speed and ease of installation. Because of this, setting it
up for the first time can be daunting, particularly if you are not familiar with
building, installing, and configuring Haskell packages.

It is our hope that this documentation makes the process as pain-free as
possible, but we invite and encourage questions about the process in the
link:irc://irc.freenode.net/noexc[#noexc channel on freenode].

== History

MapView began its life as a project for the University of Akron Amateur Radio
club's "HABP-*n*" series of balloon flights. These flights were conducted yearly
and there was a need for an effective and easy way to track the balloon.

<NAME>, N8SQL, wrote a prototype of the project in NodeJS as an experiment,
having never coded in NodeJS. The prototype got positive feedback, but Ricky
ended up realizing that NodeJS would not be a viable platform to meet the goals
of the project. A rewrite in Haskell was started on
link:https://github.com/noexc/mapview/commit/3df37823aa9bf596406cc5dbdeed004d5a167517[January 20, 2014]
and has been in active development ever since.

Alumni and former students of the University of Akron formed a new club, the
link:https://noexc.org/[Northeast Ohio Experimenters Club], and maintenance
of MapView and related projects has continued under that name. The project
continues to be led by <NAME> as new NOEXC flights incorporate new and
interesting requirements. MapView is and always will be free and open source
software and we welcome and encourage questions, contributions, and comments.

== Components

Previous versions of MapView came with several different executable, each
responsible for crunching certain kinds of data. However, this lead to us
inventing a fake IPC pipeline that did not scale well and was difficult to
configure and maintain.

MapView 3 takes a "configuration driven development" approach. That is, your
configuration file is a Haskell file which gets compiled and run. Your
configuration file **is** your MapView instance, customized exactly for your
flight.

This approach is not new. In fact, it is how the XMonad tiling window manager
works.

Here's how it works: MapView is no longer a "system." Instead, it is a library
for *creating* systems. We provide basic types to glue things together, and you
provide callbacks that work exactly how you want them to, over the data you
collect.

To make things easier for you, we provide a wide array of callbacks in the
MapView library, which you can take advantage of in your configuration. If they
don't work, you can simply write your own callback (possibly based on ours!) and
use it instead.

=== mapview: The Library

TIP: We also publish link:/haddock[haddock] documentation for this
library.

There is a common library used by all components. This includes, for example,
pieces of code for handling
link:https://en.wikipedia.org/wiki/Cyclic_redundancy_check[CRC] validation,
parsing of raw telemetry data, configuration file parsing, and datatypes and
typeclasses which are reused throughout the various components.

== Bugs, Comments, Issues

Please, please, **please** report any bugs or issues to our GitHub repositories
(mapview for the backend, mapview-psc for the frontend). We cannot fix or
discuss issues unless we know that you are having them!

General comments and questions can (and should! We don't bite!) be asked on our
{'fraction_non_alphanumeric': 0.05288595594386095, 'fraction_numerical': 0.005855562784645413, 'mean_word_length': 4.854189336235038, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4853450', 'n_tokens_mistral': 2892, 'n_tokens_neox': 2715, 'n_words': 1553}