KB1OIQ - Andy's Ham Radio Linux Files

Getting Started with Andy's Ham Radio Linux (AHRL)
==================================================

Please don't deviate from the instructions below.
Other Linux distributions which are based on Ubuntu *might* work.


These are the currently tested configurations
=============================================

  * 64-bit Raspberry Pi OS version 5.2
    * Raspberry Pi 4, 5 (8GB memory)
	
  * Ubuntu Desktop 24.04 LTS 64-bit - on Virtualbox - 8GB of memory
    * I had to hack /etc/shadow so I could login
  
  * Xubuntu 24.04 (Desktop) - on Virtualbox - 8GB memory
    - XFCE supports the multitiered menu structure preferred by AHRL

  * Kubuntu 24.04 (normal installation) - on Virtualbox - 8GB memory
	
  * Linux Mint 21.3 (Cinnamon) - on Virtualbox - 8GB memory - supported in version 26
  * Linux Mint 22 (Cinnamon)   - on Virtualbox - 8GB memory - supported in version 26a

* Some of the tested configurations don't have the multitiered menus found in XFCE.
  Thus, the AHRL menu will be one giant flat menu with 40+ entries (not very nice IMHO).
  If you have suggestions for improvement, please send them to the author.

* Sometimes a program will work on one flavor of Linux but not another.  For example,
  some programs don't work on the Raspberry Pi but work fine on other computers.  In these
  cases, it likely isn't a bug in AHRL, but please report this so I can check.


Storage requirements on Raspberry Pi (OS plus AHRL files)
=========================================================

*  8GB - not enough storage
* 16GB - adequate storage
* 32GB - plenty of storage!
* 64GB - plenty of storage!

The installation requires about 6.0GB of storage and is checked by the installation script
in a function called check_storage().


Memory requirements - all systems
=================================

*  4GB - not enough to compile source code
*  8GB - this is enough!
* 16GB - of course, more is better :-)

The installation requires at least 8GB of memory in order to compile the source code.
This is checked by the installation script in a function called check_memory().


Additional Notes
================

The ability to install the software is only one consideration.  Does your computer
have enough memory and a sufficiently fast CPU to execute that software to your
satisfaction?

In theory, this script SHOULD work on any Ubuntu based Linux distribution.
Some distributions have been tested and are listed above.  If you try something
different, please let me know the result so I can update the list of working
distributions.  If things don't work, please let me know.  It may be possible for
me to fix it to work on your favorite Ubuntu based Linux distribution.

The preference is to run this script on a clean copy of your favorite Ubuntu
based Linux distribution.  That said, you can run it on your current
setup and it should work fine.  Further, it works if you run the script today,
and then again 3 months from now to get any updated software.


INSTALLATION INSTRUCTIONS
=========================

The network (wired or wireless) MUST be working properly or the installation will fail.

One might consider installing and running xosview prior to running the installation script:
  * sudo apt install xosview
  * xosview & (or this on Raspberry Pi:  xosview -font 6x13 &)
  * Note that the load average has been measured as high as 5.0 while compiling source code.
    Ensure that your cooling fan it up to the task (especially Raspberry Pi)!
      * If not, edit the install_ahrl script and reduce NUM_CPUS.
	
Download the file from Sourceforge:
  * andy_VER.tar.gz (replacing VER with the actual version information)
  * move the file to /root (e.g. sudo mv andy_VER.tar.gz /root)
  
Install the AHRL files thus:
  * sudo -i
  * cd /usr/local
  * tar xzvf /root/andy_VER.tar.gz (again, replacing VER with the actual version information)

Run the installation script:
  * cd /usr/local/bin
  * ./install_ahrl 2>&1 | tee out.txt
  
  * While it is running, in another terminal, you can optionally do the following
    to watch the progress of the installation:

	* sudo -i
	* cd /usr/local/bin
	* tail -f out.txt | grep AHRL
	
Useful debug info will be in the file "out.txt".

To check for errors, try this:
  * sudo -i
  * cd /usr/local/bin
  * ./find_errors_ahrl
  * Let me know if you see any problems by filing a bug report (see below)
  
Some software will ask questions during the installation:
  - For dump1099, the recommended answer is "no"
  - For xastir, the recommended answer is "yes"
  - When asked "What is your username", enter the account
    where ham radio software will be run.  For example, if your
    user name is "andy", enter "andy" (without the double quotes).

Once the installation completes, if everything has gone well, check the menus
and see if there is an entry called "Andy_Ham_Radio_Linux" with many submenus.
On some systems, there won't be a menu called "Andy_Ham_Radio_Linux", but each
program will have its own menu.

Please have patience and a sense of humor if you encounter any issues.


FILING A BUG REPORT
===================

If you need to file a bug report, here's what I need.  I will try to duplicate the
issue in VirtualBox.

* the name and version of your Linux distribution
* the version of AHRL (either from the tar file or the version command)
* the out.txt file
* Please post the info on Sourceforge in the bugs module


POST INSTALLATION STEPS
=======================

On the Raspberry Pi only, WSJT-X will not display its boarder and decorations
when running Wayland.
  - One solution is to switch from Wayland to X11.  That is done as follows:
    - sudo raspi-config
    - Choose menu option 6: advanced options
    - Then choose menu option A6: wayland
    - Finally, choose menu option W1: Openbox with X11 backend
    - Reboot

AMS 18-Aug-2024