2015-02-08 12:35:16 +00:00
Getting started
===============
System requirements
-------------------
It is recommended that users run PyQSO on the Linux operating system,
since all development and testing of PyQSO takes place there.
2017-06-30 11:29:58 +00:00
As the name suggests, PyQSO is written primarily in the `Python <https://www.python.org/> `_
2018-02-13 21:02:22 +00:00
programming language (version 3.x). The graphical user interface has been developed using
2017-06-30 11:29:58 +00:00
the `GTK+ library <https://www.gtk.org/> `_ through the `PyGObject bindings <https://pygobject.readthedocs.io> `_ . PyQSO also uses an
`SQLite <https://www.sqlite.org/> `_ embedded database to manage all the contacts an amateur radio
2015-02-08 12:35:16 +00:00
operator makes. Users must therefore make sure that the Python
2018-02-13 21:02:22 +00:00
interpreter is installed and that any additional software dependencies are satisfied
2015-02-08 12:35:16 +00:00
before PyQSO can be run successfully. The list of software packages that
2015-02-08 14:36:28 +00:00
PyQSO depends on is provided in the `` README.md `` file.
2015-02-08 12:35:16 +00:00
Installation and running
------------------------
2017-07-05 22:53:28 +00:00
Assuming that the current working directory is PyQSO's base directory (the directory that the `` Makefile `` is in), PyQSO can be run without installation by issuing the following command in the terminal:
2015-02-08 12:35:16 +00:00
2015-02-08 14:38:51 +00:00
.. code-block :: bash
2017-07-05 22:53:28 +00:00
python3 bin/pyqso
2015-02-08 12:35:16 +00:00
2017-07-05 23:50:06 +00:00
If the `` pip3 `` package manager is available on your system then PyQSO can be installed system-wide using:
2015-02-08 12:35:16 +00:00
2015-02-08 14:38:51 +00:00
.. code-block :: bash
2017-07-05 23:50:06 +00:00
sudo make install
2015-02-08 12:35:16 +00:00
2017-07-05 23:50:06 +00:00
Once installed, the following command will run PyQSO:
2015-02-08 12:35:16 +00:00
2015-02-08 14:38:51 +00:00
.. code-block :: bash
2017-07-05 22:53:28 +00:00
pyqso
2015-02-08 12:35:16 +00:00
Command-line options
~~~~~~~~~~~~~~~~~~~~
There are several options available when executing PyQSO from the
command-line.
Open a specified logbook file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In addition to being able to open a new or existing logbook through the
graphical interface, users can also specify a logbook file to open at
2015-02-08 14:36:28 +00:00
the command line with the `` -l `` or `` --logbook `` option. For example, to
2015-02-08 12:35:16 +00:00
open a logbook file called `` mylogbook.db `` , use the following command:
2015-02-08 14:38:51 +00:00
.. code-block :: bash
pyqso --logbook /path/to/mylogbook.db
2015-02-08 12:35:16 +00:00
If the file does not already exist, PyQSO will create it.
Debugging mode
^^^^^^^^^^^^^^
2015-02-08 14:36:28 +00:00
Running PyQSO with the `` -d `` or `` --debug `` flag enables the debugging
2015-02-08 12:35:16 +00:00
mode:
2015-02-08 14:38:51 +00:00
.. code-block :: bash
pyqso --debug
2015-02-08 12:35:16 +00:00
2015-02-08 14:36:28 +00:00
All debugging-related messages are written to a file called `` pyqso.debug `` ,
2015-02-08 12:35:16 +00:00
located in the current working directory.
2015-02-08 15:01:33 +00:00
Creating and opening a logbook
------------------------------
2015-02-08 12:35:16 +00:00
2015-02-08 15:01:33 +00:00
A PyQSO-based logbook is essentially an SQL database. To create a new database/logbook file, click `` Create a New Logbook... `` in the `` Logbook `` menu, choose the directory where you want the file to be saved, and enter the file's name (e.g. `` my_new_logbook.db `` ). The new logbook will then be opened automatically. If you would like to open an *existing* logbook file, click `` Open an Existing Logbook... `` in the `` Logbook `` menu. Note that logbook files usually have a `` .db `` file extension.
2015-02-08 12:35:16 +00:00
2015-02-28 14:53:02 +00:00
Once the logbook has been opened, its name will appear in the status bar. All logs in the logbook will be opened automatically, and the interface will look something like the one shown in figure:logbook_.
2015-02-08 12:35:16 +00:00
2015-02-28 14:53:02 +00:00
.. _figure: logbook:
.. figure :: images/logbook.png
2015-02-08 14:36:28 +00:00
:align: center
2018-04-01 19:31:04 +00:00
The PyQSO main window, showing the records in a log called `` SO50 `` (for contacts via the `amateur radio satellite <https://www.amsat.org/> `_ SO-50), and the World Map tool in the toolbox below it.
2015-02-08 12:35:16 +00:00
Closing a logbook
-----------------
2015-02-08 15:01:33 +00:00
A logbook can be closed by clicking the `` Close Logbook `` button in the toolbar, or by clicking `` Close Logbook `` in the `` Logbook `` menu.
2015-02-08 12:35:16 +00:00