ham-0.1.0.0: README.org

* HamLog
** User manual for the hamlog program
   This can be found here: [[file:doc/user_manual.org]]
** Introduction
This is the attempt to make a console based logging application
for Ham Radio contacts.
It is meant to be simple and fast to use,
but additional useful features may be added in the future.
There are two parts:
1. The Ham library, providing functions for creating and modifying
   contact lists.
2. The hamlog user facing application.
The two parts are separate, and most of the actual functionality is
kept in the library, so other applications using the library can easily be built
without having to replicate the functionalities that have nothing
to do with user interfaces.

* State of Development
This is not really mature, but
it is being used by some on a daily basis.

* Compiling
Get GHC and Cabal using e.g. [[https://www.haskell.org/ghcup/]].
Run
#+begin_src shell
cabal configure
cabal build
#+end_src
This should technically build on any system that supports all the
needed libraries, which probably include macOS and Windows along with Linux.
This has only been tried on Linux and macOS.

* Library Usage
The HamLog monad is meant as an easy to use back end to
manipulate log lists.
A usage example would be:
#+begin_src haskell
runHamLog defaultConfig emptyLogState $ do
   readLog
   q <- newQsoNow
   updateQso 0 $ q { _qsoFreqency = MHz 146.52,
                     _qsoNotes    = "Nice contact!" }
   writeLog
#+end_src
Note that some things in this library are subject to change still.
See the source for details.

* CAT Interface
There is a CAT (computer aided transceiver) interface included.
Currently, the Yaesu FT-891 and the Elecraft K3/KX2/KX3 are supported.

** Adding support for another radio
Basically, the steps you need to do to support a new radio are simple:
See the module Ham.CAT.SerialCAT; you need to add a set of functions in a SerialCAT structure.
Check out the ones in Ham.CAT.YaesuFT891 and Ham.CAT.ElecraftKX2 for examples.
It is currently assumed that the radio is connected using a serial interface, e.g. via USB.
Note this interface may change in the future.
Steps for adding a radio:
- Add a SerialCAT interface and put it in a module in Ham.CAT, just like the existing radios.
- Add a constructor for the new radio in Ham.CAT.Radios.Radio.
- Add the SerialCAT interface to serialInterface in Ham.CAT.Radios.

Each of these steps is really not much to do, the most work is probably the first one.

The terminal UI supports reading the frequency and the current communications mode when
creating a new contact.
This functionality can be accessed in the `HamLog` monad also via the `cat` action.

* Todo List
** TODO Minimal ADIF export to support LOTW
** TODO ADIF import?
** TODO Add versioning for files and data structures. Support converting from older versions.
   - Note taken on [2020-09-05 Sat 13:22] \\
     Works for hamlog.config. Need to add some error reporting if something fails.
     Need to add support for versioning the log file.
** DONE Integrate getting values for new QSOs via CAT into HamLog.
   Currently that is done in the Brick UI.
** DONE Connection to radio
   - Note taken on [2020-09-05 Sat 13:21] \\
     Works so far SerialCAT implemented for FT891 and KX2/K3/KX3
   - Note taken on [2020-08-15 Sat 23:01]
     Support for Yaesu FT891 works, everything compiled in so far.
*** DONE Add error handling to CAT
*** DONE Separate the serial interface for particular radios from CAT.hs
*** DONE Write / read configuration from disk.
    Currently it's compiled in.
** DONE Hand Writer [Text] result to the UI for the Info window.
** DONE [#A] Make the Info window scrollable and fixed height.
   It messes up the UI if there are many messages.
** TODO Compute distances between locations
** TODO Add Cabrillo output to Contest typeclass.
** TODO Update QSO time while typing QSO.
   Update the UTC time with e.g. CTRL-T.
** TODO End time optional
** TODO Add an ID to each QSO
   This would help to find duplicates. Until then, use everything, including date/time,
   to find actual duplicates, minus the one we are searching for.
** TODO Fix callsign lookup
** TODO Search QSOs.
** TODO For searching and dupe checks, add hash table?
** TODO Tags, grouping by tags.
** TODO Multiple selection?
** TODO Scrollable notes, if necessary.
** TODO Application hangs when radio is not connected.
   - Note taken on [2020-09-06 Sun 23:06] \\
     Mitigation implemented. Not very pretty, but at least it happens only once per session at maximum.
   - Note taken on [2020-09-06 Sun 14:06] \\
     closeSerial blocks after writing / reading when the serial device exists
     but is not connected.
     There is no immediate way to get around that.
     Mitigation: add error reporting to CAT and after first failure,
     turn CAT off and let the user know.
   Add error checks!
   This happens when the serial port is configured to the wrong file node.
** [#B] Multiple log files?
   - Note taken on [2018-07-28 Sat 23:06] \\
     This is simply possible by keeping log files in separate directories, along with configurations.
** DONE Sanitize QSOs when updating / creating.
   Remove leading and trailing whitespaces, possibly toUpper, etc.
** DONE Point calculation NAQP
   Add instance for Contest typeclass.
** DONE Dupe check
   - Note taken on [2020-07-07 Tue 00:21] \\
     More or less done.
** DONE Mode should stay the same for new contacts
** DONE Point calculation FieldDay
   - Note taken on [2020-06-30 Tue 23:03] \\
     Done.
** DONE [#A] Export to Cabrillo, configurable.
   - Note taken on [2020-06-30 Tue 23:00] \\
     Sort of works.
** DONE Values for exchanges at contests.
   CLOSED: [2018-07-28 Sat 23:05]
   - Note taken on [2018-07-28 Sat 23:05] \\
     Default values have been added to the config structure.
     See QsoDefaults. FixedValue means the UI does not display the value,
     DefaultValue means the UI displays it but pre-populates with the given value
     in the config file.
     This way the application can be configured to work better in contests.