Setting up MaRGE and MaRCoS from scratch - josalggui/MaRGE GitHub Wiki

Installation for Users

Index

  1. Requirements
  2. Install MaRGE from PyPI
  3. Install MaRGE from source
  4. Set up the Red Pitaya and the Host computer (not valid for Windows).

1. Requirements

System Requirements

  1. Operating System

    • The full setup process has been tested on Ubuntu 22.04.5 LTS.
    • Windows users can install MaRGE, but cannot set up the MaRCoS server or client using this method.
    • On Windows, MaRCoS server/client installation must follow the legacy method.

  2. Python 3

    • Python 3 must be installed on your system.
    • Tested versions:
      • Python 3.10 on Ubuntu
      • Python 3.13 on Windows

  3. Internet Connection

    • Required for installation and dependency setup.

Hardware Requirements (Full Functionality)

To use MaRGE with full functionality, you must have a working MaRCoS system, including:

  • A Red Pitaya board with the MaRCoS server installed
  • A host computer configured as a MaRCoS client
  • Static IP networking between the host and the Red Pitaya

If MaRCoS + Red Pitaya is not configured, MaRGE can still be launched in Trial Mode, but hardware acquisition features will not be available.

1. Install MaRGE from PyPI

MaRGE is available on PyPI, making it easy to install with pip.
This option is ideal for users who want to use the existing sequences and toolkits.
If you plan to customize or add sequences, modify the GUI, or develop new features, proceed to the next section.

Installation

Install MaRGE with pip if you only need to run the GUI and do not plan to modify the source code or add custom sequences.

Note: Tyger capabilities are not supported from pip installation.

  1. Go to your project folder.Create and activate a virtual environment:

    • Ubuntu 
      python3 -m venv venv
source venv/bin/activate
    • Windows 
      python -m venv venv
source venv/Scripts/activate

  2. Install marge-mri

    pip install marge-mri==1.0.0b2

  3. Launch the GUI from terminal:

      marge-mri

  4. Configure your session and hardware following this link.

Project Folder Structure

Once you launch MaRGE for the first time, it automatically creates the required folder structure and configuration files in the current working directory. Some files are created once you access to the Main window by the first time, so do not scare if you miss some files now. Example folder structure:

project-folder/
β”œβ”€β”€ calibration/                   ← protocols for autocalibration
β”œβ”€β”€ configs/                       ← device configuration and hardware settings
β”œβ”€β”€ experiments/                   ← acquired raw data (main output)
β”œβ”€β”€ logs/                          ← runtime logs and debugging info
β”œβ”€β”€ protocols/                     ← protocols defined by the user
β”œβ”€β”€ reports/                       ← reports generated by the user
β”œβ”€β”€ communicateRP.sh               ← script to interact with Red Pitaya
β”œβ”€β”€ copy_bitstream.sh              ← helper to load FPGA bitstream
β”œβ”€β”€ marcos_fpga_rp-122.bit         ← MaRCoS files
β”œβ”€β”€ marcos_fpga_rp-122.bit.bin     ← MaRCoS files
β”œβ”€β”€ marcos_fpga_rp-122.dtbo        ← MaRCoS files
β”œβ”€β”€ ps_interpreter.log             ← low-level interpreter log
β”œβ”€β”€ marcos_install.sh              ← script to set up a red pitaya, configuring the server and client
β”œβ”€β”€ readme.org                     ← MaRCoS files documentation

πŸ“Œ Notes:

The experiments/ folder is the most relevant for users:
It stores all acquired raw data, organized by timestamp and experiment name.

Make sure to run MaRGE from the folder where you want this structure to be created.

You can safely delete or move these folders between sessions; MaRGE will recreate them if needed.

2. Install MaRGE from source

Installing MaRGE from source is recommended for users who want full control over the codebase.
This option allows you to modify existing sequences, extend the GUI, contribute new features, or adapt MaRGE to your specific workflows.

  1. Go to the folder where you want to create the project and clone the repo

    git clone https://github.com/josalggui/MaRGE.git

  2. Go into the created MaRGE folder. Create and activate a virtual environment. Then, add the current folder (MaRGE) to Python's module search path:

    • Ubuntu 
      cd MaRGE
python3 -m venv venv
source venv/bin/activate
export PYTHONPATH=$(pwd)
    • Windows 
      cd MaRGE
python -m venv venv
source venv/Scripts/activate
export PYTHONPATH=$(pwd)

  3. Install requirements

    pip install -r requirements.txt

  4. Go into MaRGE/marge folder and run the main.py.

    • Ubuntu 
      cd marge
python main.py
    • Windows 
      cd marge
python3 main.py

  5. Configure your session and hardware following this link.

Project Folder Structure

Once you launch MaRGE for the first time, it automatically creates the required folder structure and configuration files in the current working directory. Some files are created once you access to the Main window by the first time, so do not scare if you miss some files now. Example folder structure:

MaRGE/
β”œβ”€β”€ marge
β”œβ”€β”€β”€β”€ autotuning/                    ← RFAutoMaTE related files 
β”œβ”€β”€β”€β”€ calibration/                   ← protocols for autocalibration
β”œβ”€β”€β”€β”€ configs/                       ← device configuration and hardware settings
β”œβ”€β”€β”€β”€ controller/                    ← scripts to control the behavior of the GUI
β”œβ”€β”€β”€β”€ docs/                          ← documents for sphinx
β”œβ”€β”€β”€β”€ experiments/                   ← acquired raw data (main output)
β”œβ”€β”€β”€β”€ logs/                          ← runtime logs and debugging info
β”œβ”€β”€β”€β”€ manager/                       ← dicom manager
β”œβ”€β”€β”€β”€ marcos/                        ← marcos files
β”œβ”€β”€β”€β”€ marge_tyger/                   ← tyger scripts
β”œβ”€β”€β”€β”€ marge_utils/                   ← usefull standalone methods
β”œβ”€β”€β”€β”€ protocols/                     ← protocols defined by the user
β”œβ”€β”€β”€β”€ recon/                         ← standalone reconstruction methods
β”œβ”€β”€β”€β”€ reports/                       ← reports generated by the user
β”œβ”€β”€β”€β”€ resources/                     ← folder that contains images and icons
β”œβ”€β”€β”€β”€ seq/                           ← sequences (can be executed in standalone)
β”œβ”€β”€β”€β”€ ui/                            ← scrits with the user interface windows
β”œβ”€β”€β”€β”€ vna/                           ← scripts related to the nanovna
β”œβ”€β”€β”€β”€ widgets/                       ← widget used to build the ui
β”œβ”€β”€β”€β”€ communicateRP.sh               ← script to interact with Red Pitaya
β”œβ”€β”€β”€β”€ main.py                        ← Main script to run MaRGE
β”œβ”€β”€β”€β”€ marcos_install.sh              ← script to set up a red pitaya, configuring the server and client
β”œβ”€β”€β”€β”€ ps_interpreter.log             ← low-level interpreter log
β”œβ”€β”€ README.md                        ← MaRGE readme file
β”œβ”€β”€ pyproject.toml                   ← pypi related file
β”œβ”€β”€ setup.py                         ← pypi related file
β”œβ”€β”€ MANIFEST.in                      ← pypi related file
β”œβ”€β”€ requirements.txt                 ← required modules to make it work properly

3. Set up the Red Pitaya and the Host computer (Ubuntu).

  1. Execute the marcos_install.sh file as sudo user. There are three alternatives to access the file:

    1. If MaRGE is already in the computer, find it in the marge folder.
    2. Download the file from this link.
    3. Run the main GUI and call it from button located in the MaRCoS toolbar (only if hardware is already configured).

    For options i. and ii., execute the file as sudo user:

    sudo ./marcos_install.sh

  2. Follow the instructions indicated in the terminal.

The marcos_install.sh script will guide the user through the full process from inserting the SD card into your computer up to installing MaRCoS server into the red pitaya. The steps followed by the script are:

  1. Download the OS image (if not already present).
  2. Extract the image archive (if needed).
  3. Write the image to the SD card.
  4. Mount the SD card’s root partition.
  5. Set a static IP for the Red Pitaya.
  6. (Optional) Configure the host PC Ethernet interface.
  7. Modify client computer Ethernet configuration.
  8. Remove old SSH keys for the Red Pitaya and add the new one.
  9. Install and configure the MaRCoS server on the Red Pitaya.

Just follow the instructions to configure your SD card, Ethernet port, server, and client.

button

Warning

  1. This script will modify your Ethernet configuration, a backup will be created in /etc/netplan
  2. .ssh/known_hosts ownership will pass from user to sudo user
  3. Run this script under your own risk.