Zaxcom VRX for Linux (AppImage)
===============================

The AppImage is a single file that contains the Zaxcom VRX app. It does not need to be
installed: download it, allow it to run, and open it.


What you need
-------------

- A 64-bit Intel/AMD PC (x86_64).
- A Linux distribution from 2022 or later, for example:
    Ubuntu 22.04 or newer, Linux Mint 21 or newer, Debian 12 or newer, Fedora 36 or
    newer, RHEL / Rocky / AlmaLinux 9 or newer, Arch, Manjaro, openSUSE Tumbleweed.
  Older releases (such as Ubuntu 20.04 or RHEL 8) cannot run it.
- A normal desktop (GNOME, KDE Plasma, Xfce, Cinnamon, MATE, ...). Standard desktop
  installs already have everything the app needs. See "If the app does not start" for
  minimal installs.


1. Make the file executable (once)
----------------------------------

Downloaded files are not allowed to run until you say so. (Skip this step if you
unpacked the AppImage from the .tar.gz archive: it is already executable.)

  File manager: right-click the .AppImage file > Properties > Permissions, and tick
  "Allow executing file as program" (or "Is executable").

  Terminal (in the folder with the file):
      chmod +x zaxcom-vrx-*.AppImage


2. Allow access to the VRX's USB port (once)
--------------------------------------------

Linux does not let ordinary users open USB serial devices by default. Do ONE of these:

  A) Recommended: install the VRX access rule. In a terminal, in the folder with the file:
         ./zaxcom-vrx-*.AppImage --install-udev-rule
     Enter your password when asked. If the VRX is plugged in, unplug it and plug it back
     in. This also stops the system's modem service from sending commands to the VRX.

  B) Or add yourself to the serial port group, then log out and back in (or restart):
         Ubuntu, Mint, Debian, Fedora, RHEL, openSUSE:   sudo usermod -aG dialout $USER
         Arch, Manjaro:                                  sudo usermod -aG uucp $USER

If you skip this step, the app opens but shows "A VRX was found but could not be opened
... Permission denied".


3. Run the app
--------------

Double-click the .AppImage file, or run it from a terminal:
    ./zaxcom-vrx-*.AppImage

Connect the VRX with its USB cable. With no VRX connected the app starts from the Zaxcom
factory defaults, so you can prepare settings and presets first, then connect each unit
and press WRITE VRX.

Your presets are saved in:
    ~/.local/share/com.zaxcom.vrx_app/presets.json
They are kept when you replace the AppImage with a newer version.


If the app does not start
-------------------------

Run it from a terminal to see the error message, then find it below.

"error while loading shared libraries: libgtk-3.so.0" (or libgdk-3, libpango, libcairo,
libatk, libepoxy, libfontconfig, libudev, ...)
    A desktop library is missing; this happens on minimal installs and some KDE-only
    systems. Install GTK 3, which brings the others with it:
        Ubuntu, Mint, Debian:   sudo apt install libgtk-3-0 libepoxy0
                                (Ubuntu 24.04 and newer: libgtk-3-0t64 libepoxy0)
        Fedora, RHEL, Rocky:    sudo dnf install gtk3 libepoxy
        Arch, Manjaro:          sudo pacman -S gtk3 libepoxy
        openSUSE:               sudo zypper install libgtk-3-0 libepoxy0
    If one more library is still reported missing, search your distribution's packages
    for the file name shown in the message.

"version `GLIBC_2.34' not found"
    The distribution is too old. Use one of the releases listed under "What you need".

"fusermount: not found", "Cannot mount AppImage" or a message about FUSE
    AppImages use FUSE to open themselves. Either install it:
        Ubuntu, Mint, Debian:   sudo apt install fuse3
        Fedora, RHEL, Rocky:    sudo dnf install fuse3
        Arch, Manjaro:          sudo pacman -S fuse3
        openSUSE:               sudo zypper install fuse3
    or start the app without FUSE:
        ./zaxcom-vrx-*.AppImage --appimage-extract-and-run

"Permission denied" when starting the file
    The file is not executable yet; see step 1. If it still fails, the folder may be on a
    drive mounted with "noexec" (some USB sticks and shared folders): copy the file to
    your home folder and run it from there.


If the VRX is not found
-----------------------

- "No VRX connected" stays on screen: try another cable (some cables only charge) or
  another USB port, and check that the VRX is switched OFF WITH batteries installed.
- "A VRX was found but could not be opened ... Permission denied": do step 2, then
  unplug and reconnect the VRX (after option B, log out and back in first).
- "... could not be opened ... Device or resource busy": another program is using the
  VRX. Close other copies of this app and any serial terminal programs, then reconnect.


Removing the app
----------------

Delete the .AppImage file. If you installed the access rule (step 2 A), remove it with:
    sudo rm /etc/udev/rules.d/60-zaxcom-vrx.rules
To also remove your presets, delete the folder ~/.local/share/com.zaxcom.vrx_app
