Serial port communication
=========================

The HotRIO microcontroller software provides easy access to all its functionalities through a standardised CLI-based interface. This interface allows the maintainer to perform all the needed managing actions on the microcontroller and upload/download configurations by using a standard serial port.

The developer and user can interact with the microcontroller through a serial port terminal emulator such as 'minicom', which provides a simple and efficient way to communicate with the microcontroller. As the microcontroller also supports the Kermit protocol, the user can upload and download files from the microcontroller filesystem using the Kermit protocol.

This document provides a detailed guide for packaging `minicom` and `ckermit` into a self-contained AppImage. The resulting AppImage will allow the applications to run on any Linux system without requiring installation or dependencies.

The user does not need to follow the steps below to use the AppImage. The AppImage is available for download from the `HotRIO repository on SVN <https://vcis.f4e.europa.eu/svn/45CODAC-HOTRio/trunk/SoftwareTools/Minicom/>`_.

Creating an AppImage for Minicom and Kermit
-------------------------------------------

This document provides a detailed guide for packaging `minicom` and `ckermit` into a self-contained AppImage. The resulting AppImage will allow the applications to run on any Linux system without requiring installation or dependencies.

Prerequisites
~~~~~~~~~~~~~
Ensure the necessary dependencies are installed:

.. code-block:: bash

    sudo apt update
    sudo apt install build-essential wget fuse libfuse2

AppDir Folder Structure
~~~~~~~~~~~~~~~~~~~~~~~
The AppImage format relies on a structured directory known as `AppDir`, which mimics a minimal root filesystem containing the necessary binaries, libraries, and resources.

The required folder structure is as follows:

.. code-block:: bash

    MinicomKermit.AppDir/
    ├── AppRun                              # Entry script for the AppImage
    ├── minicom.desktop                     # Desktop entry file
    ├── usr/
    │   ├── bin/
    │   │   ├── minicom                     # Minicom binary
    │   │   ├── kermit                      # Kermit binary
    │   ├── lib/                            # Required shared libraries
    │   ├── share/
    │   │   ├── configurations/             # Configuration files folder
    │   │   │   ├── kermit.cfg              # Kermit configuration file
    │   │   │   ├── minirc.dfl              # Minicom default configuration for HotRIO usage
    │   │   ├── icons/hicolor/256x256/apps/
    │   │   │   ├── minicom.png             # Application icon


Step 1: Create the AppDir Structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Prepare the directory layout:

.. code-block:: bash

    mkdir -p MinicomKermit.AppDir/usr/bin
    mkdir -p MinicomKermit.AppDir/usr/lib
    mkdir -p MinicomKermit.AppDir/usr/share/configurations
    mkdir -p MinicomKermit.AppDir/usr/share/icons/hicolor/256x256/apps

Step 2: Copy the Minicom Binary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Locate the installed `minicom` binary and copy it into `AppDir`:

.. code-block:: bash

    MINICOM_BIN=$(whereis -b minicom | awk '{print $2}')
    cp "$MINICOM_BIN" MinicomKermit.AppDir/usr/bin/

Copy all dynamically linked libraries required by `minicom`:

.. code-block:: bash

    ldd "$MINICOM_BIN" | awk '{print $3}' | grep -v "^(" | xargs -I '{}' cp '{}' MinicomKermit.AppDir/usr/lib/

Step 3: Compile and Install Kermit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Download and compile the latest version of `ckermit` from the Kermit Project's daily update page:

To do so, go to the daily update page `here <https://www.kermitproject.org/ckdaily.html>`_ and download the latest `ckermit` source tarball. Extract the tarball, compile the source code, and copy the resulting binary into the `AppDir/usr/bin` directory. The executable created by the compilation process is named `wermit`, so rename it to `kermit` before copying it into the `AppDir`:

.. code-block:: bash

    wget https://www.kermitproject.org/ftp/kermit/test/tar/x.tar.gz 
    tar -xzf x.tar.gz 
    make linux
    cp wermit ../../MinicomKermit.AppDir/usr/bin/kermit

Step 4: Create the AppRun Script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `AppRun` script is the main entry point of the AppImage and is responsible for setting up the environment before launching the application.

Create the `AppRun` script with the following content:

.. code-block:: bash
    
    #!/bin/bash
    HERE="$(dirname "$(readlink -f "${0}")")"
    export LD_LIBRARY_PATH="$HERE/usr/lib:$LD_LIBRARY_PATH"
    export MINICOM="$HERE/usr/share/configurations/minirc.dfl"
    echo $MINICOM
    "$HERE/usr/bin/minicom" "$@"

This code simply sets the `LD_LIBRARY_PATH` environment variable to include the `usr/lib` directory of the AppDir and then launches `minicom` with the default configuration file `minirc.dfl` from the AppImage. 

Make the script executable so it can be used during the execution of the AppImage:

.. code-block:: bash
    
    chmod +x MinicomKermit.AppDir/AppRun

Step 5: Create the Desktop Entry and Icon
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A `.desktop` file is required for integration with desktop environments. Create the `minicom.desktop` file on the `AppDir` root with the following content:

.. code-block:: bash

    [Desktop Entry]
    Type=Application
    Name=Minicom
    Exec=minicom
    Icon=/usr/share/icons/hicolor/256x256/apps/minicom
    Categories=Utility;TerminalEmulator;
    Terminal=true

Copy an appropriate icon for the application:

.. code-block:: bash

    cp /usr/share/icons/hicolor/256x256/apps/minicom.png MinicomKermit.AppDir/usr/share/icons/hicolor/256x256/apps/minicom.png

Step 6: Download and Use `appimagetool`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Obtain the `appimagetool` binary to package the AppImage:

.. code-block:: bash

    cd /tmp
    wget https://github.com/AppImage/AppImageKit/releases/latest/download/appimagetool-x86_64.AppImage
    chmod +x appimagetool-x86_64.AppImage

Step 7: Build the AppImage
~~~~~~~~~~~~~~~~~~~~~~~~~~

Depending on the target host architecture, the ARCH variable needs to be set to either `x86_64` or `i686` for appimagetool to generate the correct AppImage. Take into consideration that the binaries and libraries supplied for such AppImage must also comply with the required target architecture.

.. code-block:: bash

    export ARCH=x86_64

or 

.. code-block:: bash

    export ARCH=i686


Generate the final AppImage using `appimagetool`:

.. code-block:: bash

    ./appimagetool-x86_64.AppImage MinicomKermit.AppDir MinicomKermit.AppImage

Step 8: Execute the AppImage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Run the newly created AppImage, by firstly making it executable if it is not already:

.. code-block:: bash

    chmod +x MinicomKermit.AppImage
    ./MinicomKermit.AppImage

The resulting AppImage provides a portable environment for running Minicom with Kermit on any Linux distribution without requiring installation or dependencies.