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. Full MaRCoS Setup (Red Pitaya Server and Host Computer Client)
  5. Set up the client Ethernet port (Ubuntu 22.04 LTS)
  6. Set up the client Ethernet port (Ubuntu 24.04 LTS and 26.04 LTS)
  7. Set up the client Ethernet port (Windows)
  8. Setting up the MaRCoS server (Red Pitaya) with a static IP
  9. Connecting the MaRCoS Client and Server

1. Requirements

Supported Operating Systems

MaRGE has been tested on the following operating systems:

Operating System Status
Ubuntu 22.04.5 LTS Supported
Ubuntu 24.04 LTS Supported
Ubuntu 26.04 LTS Supported
Windows 10 Supported
Windows 11 Supported

Note for Ubuntu 26.04 LTS

Ubuntu 26.04 LTS uses Ptyxis as the default terminal emulator. During testing, some minor issues were encountered when connecting to the server from Ptyxis. For the most reliable experience, it is recommended to use GNOME Terminal instead.

sudo apt update
sudo apt install gnome-terminal

Note for Windows

Installation of the MaRCoS server from a Windows is supported only through the legacy setup procedure described in the wiki. Alternatively, the MaRCoS server can be installed from a supported Ubuntu system and later used from a Windows computer running MaRGE. Git Bash must be installed, as MaRGE uses it to communicate with the Red Pitaya.

Python Requirements

Python 3 is required.

Tested Python versions

Python Version Platform Supported MaRGE Versions
3.10 Ubuntu 22.04 LTS Up to v1.0.0b3
3.12 Ubuntu 24.04 LTS From v1.0.0b4
3.14 Ubuntu 26.04 LTS From v1.0.0b4
3.13 Windows 10/11 Supported with Git Bash

Other Python 3 versions may work but have not been formally tested.

Required Python Tools

The following tools must be available for the selected Python installation:

  • pip (Python package manager)
  • venv (Python virtual environment support)
  • git (required to clone repositories and install some dependencies)

On Ubuntu, these packages can be installed with:

sudo apt install git python3-pip python3-venv

If multiple Python versions are installed, ensure that pip and venv correspond to the Python version used for MaRGE.

Network Requirements

Internet Connection

An active internet connection is required during installation to download dependencies and complete the setup process.

Ethernet Connectivity

A dedicated Ethernet connection to the Red Pitaya is required.

  • MaRGE communicates with the Red Pitaya using a static IP configuration.
  • During the server and client setup process (Section 4 of the installation tutorial), the Ethernet interface is configured automatically on Ubuntu systems.
  • If only Ethernet configuration is needed, follow Sections 5, 6, or 7 of the tutorial according to your operating system.

Hardware Requirements

Required Hardware

  • Red Pitaya board
  • Available Ethernet port on the host computer

Summary

Minimum Requirements

  • Supported operating system (Ubuntu 22.04+, Ubuntu 24.04+ for the latest releases, or Windows 10/11)
  • Python 3
  • pip and venv for the selected Python installation
  • git
  • Internet connection for installation
  • Available Ethernet port
  • Red Pitaya device
  • Git Bash (Windows only)

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. The MaRCoS setup procedure is described in Section 4.

2. 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. (Ubuntu only) Install Qt system libraries

    Some Ubuntu installations may be missing libraries required by Qt applications. Before running MaRGE by the first time, install the required system packages:

    sudo apt update
sudo apt install -y \
 libxcb-cursor0 \
 libxcb-xinerama0 \
 libxcb-icccm4 \
 libxcb-image0 \
 libxcb-keysyms1 \
 libxcb-render-util0 \
 libxkbcommon-x11-0 \
 libxcb-randr0 \
 libxcb-shape0 \
 libxcb-xfixes0 \
 libgl1 \
 libegl1

  2. Go to your project folder and create and activate a virtual environment:

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

  3. Install marge-mri

    pip install marge-mri==1.0.0b2

  4. Launch the GUI from terminal:

      marge-mri

  5. Configure your MaRGE session and hardware by following this Hardware Configuration Guide.

    Prerequisite: Hardware configuration requires a working MaRCoS installation (Red Pitaya server, host computer client, and network connection).

    If you have not yet installed and configured MaRCoS, you will need to install MaRCoS after MaRGE installation. Section 4: Full MaRCoS Setup (Red Pitaya Server and Host Computer Client).

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.

3. 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. Note that the commands indicated here for Windows run on GitBash, not in PowerShell.

  1. (Ubuntu only) Install Qt system libraries

    Some Ubuntu installations may be missing libraries required by Qt applications. Before running MaRGE by the first time, install the required system packages:

    sudo apt update
sudo apt install -y \
 libxcb-cursor0 \
 libxcb-xinerama0 \
 libxcb-icccm4 \
 libxcb-image0 \
 libxcb-keysyms1 \
 libxcb-render-util0 \
 libxkbcommon-x11-0 \
 libxcb-randr0 \
 libxcb-shape0 \
 libxcb-xfixes0 \
 libgl1 \
 libegl1

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

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

  3. 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)

  4. Install requirements

    pip install -r requirements.txt

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

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

  6. Configure your MaRGE session and hardware by following this Hardware Configuration Guide.

    Prerequisite: Hardware configuration requires a working MaRCoS installation (Red Pitaya server, host computer client, and network connection).

    If you have not yet installed and configured MaRCoS, you will need to install MaRCoS after MaRGE installation. Section 4: Full MaRCoS Setup (Red Pitaya Server and Host Computer Client).

Note 1

When you run main.py additional folders are created to save results, configurations, and calibrations data. These folders are created in the directory from which main.py is executed. For this reason, it is strongly recommended to run main.py from MaRGE/marge directory.

Note 2

export PYTHONPATH=$(pwd) command is required each time you initialize the virtual environment, unless it has been added to the virtual activation script. Some IDEs, such as Pycharm and Visual Studio Code, may automatically configure the Python path or working directory when launching the project, making this step unnecessary.

Note 3

The commands provided for Windows have been tested with Git Bash and should work as expected. As indicated in the requirements, Git Bash is required to run MaRGE on Windows; therefore, it is also recommended to use Git Bash during the installation process. For PowerShell environments, some commands may require adaptation to PowerShell syntax.

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

4. Full MaRCoS Setup (Red Pitaya Server and Host Computer Client)

This is the recommended setup method for Ubuntu users. The marcos_install.sh script performs the complete MaRCoS installation and configuration process, including:

  • Preparing the Red Pitaya SD card
  • Installing and configuring the MaRCoS server
  • Assigning the Red Pitaya static IP address
  • Configuring the host computer Ethernet interface
  • Updating SSH keys and client configuration
  • Installing Tyger in the host computer

If you successfully complete this section, you do not need to follow Sections 5 or 6 manually. Those sections are provided only for users who need to configure the Ethernet interface separately or troubleshoot network settings.

Who should use this section?

Use this procedure if you are setting up a new Red Pitaya or a new MaRCoS installation from scratch on Ubuntu. The script automates both server and client configuration and is the fastest way to obtain a working MaRCoS environment.

The procedure described in this section has been developed and tested on Ubuntu systems. Other Linux distributions may not be compatible, and Windows or macOS are not supported.

  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.
  10. Install Tyger into the Host computer

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.

5. Set up the client Ethernet port (Ubuntu 22.04 LTS)

Steps

  1. Open Netplan Configuration File: 
    cd /etc/netplan
sudo nano 01-network-manager-all.yaml
  2. Edit the Configuration File:
    • Modify the file to include the following configuration (replace **your_ethernet_interface** with the actual name of your Ethernet interface, which you can find by typing ifconfig in the terminal): 
      network:
  version: 2
  renderer: NetworkManager
  ethernets:
    **your_ethernet_interface**:
       dhcp4: no
       addresses: [192.168.1.100/24]
       gateway4: 192.168.1.1
       nameservers:
         addresses: [8.8.8.8, 8.8.4.4]
  3. Apply the Configuration:
    • Save and exit the editor.
    • Apply the configuration by typing: 
      sudo netplan try
    • Confirm the changes when prompted.
  4. Restart the Computer:
    • After restarting, verify the IP address by typing ifconfig in the terminal. You should see 192.168.1.100 assigned to your Ethernet interface.

6. Set up the client Ethernet port (Ubuntu 24.04 LTS)

Note: New versions of Ubuntu allows to do the network configuration through the graphical interface. The method described in previous section still work (tested on Ubuntu 26.04 LTS), but here I add information about how to do the configuration from the Ubuntu graphical interface.

  1. With the Red Pitaya connected to the computer, open the Ethernet configuration
  2. Click on the configuration button corresponding to the Ethernet interface you want to configure
  3. Select the IPv4 tab, and configure a Manual IP address as indicated. A different IP address can be configured, but it needs to be compatible with the IP of the red pitaya.

7. Set up the client Ethernet port (Windows)

Steps:

  1. Open Network Connections:
    • Press Windows + R to open the Run dialog box.
    • Type ncpa.cpl and press Enter to open the Network Connections window.
  2. Access Ethernet Properties:
    • Right-click on your Ethernet connection and select Properties.
  3. Select IPv4 Properties:
    • In the Ethernet Properties window, select Internet Protocol Version 4 (TCP/IPv4) and click on the Properties button.
  4. Configure Static IP:
    • In the Internet Protocol Version 4 (TCP/IPv4) Properties window, select Use the following IP address.
    • Enter the following details:
      • IP address: 192.168.1.100
      • Subnet mask: 255.255.255.0
    • Select Use the following DNS server addresses and leave them blank.
  5. Save and Exit:
    • Click OK to save the changes and close the properties window.
    • Click Close to close the Ethernet Properties window.

image

8. Setting up the MaRCoS server (Red Pitaya) with a static IP

Steps

  1. Insert the SD Card: Insert the SD card into your computer SD card slot.
  2. Download compressed SD image.
  3. Extract SD image. 
    tar -xvf sdimage-bootpart-202004030120-mmcblk0.direct.tar.bz2
  4. Flash SD image into the SD card. 
    sudo dd if=./sdimage-bootpart-202004030120-mmcblk0.direct of=/dev/mmcblk0 bs=1M && sync
    where /dev/mmcblk0 is the SD card device; it may be different on your system.
  5. Access the Network Configuration File: Navigate to the /etc/network file inside the SD card. Then open the interfaces file: 
    sudo nano interfaces
  6. Modify interfaces file: Replace the # Wired or wireless interfaces section with the following content to set a static IP: 
    # Wired or wireless interfaces
auto eth0
iface eth0 inet static
   address 192.168.1.101
   netmask 255.255.255.0
   gateway 192.168.1.1
  7. Save and Exit: Save the changes and safely remove the SD card.
  8. Insert the SD Card into Red Pitaya.

This fixes the IP of your sever to 192.168.1.101.

9. Connecting the MaRCoS Client and Server

Once the Red Pitaya has been configured and the host computer Ethernet interface has been set up, connect both devices using an Ethernet cable.

Verify the Connection

  1. Connect the Red Pitaya to the Host Computer

    • Use an Ethernet cable to connect the Red Pitaya directly to the configured Ethernet port on your computer.

  2. Access the Red Pitaya via SSH

  3. Verify Access

    • If the connection is successful, you should obtain a shell prompt on the Red Pitaya and be able to interact with the MaRCoS server.

First Connection

If this is the first time you connect to the Red Pitaya, your SSH client may ask you to verify the host authenticity:

The authenticity of host '192.168.1.101 (192.168.1.101)' can't be established.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Type yes and press Enter to continue. The Red Pitaya will then be added to your list of known SSH hosts.

If the MaRCoS server was installed using marcos_install.sh, the SSH keys should already have been configured automatically and the connection may proceed without additional prompts.

SSH Host Key Changes

If the Red Pitaya has been reinstalled, reimaged, or configured with a different SD card, SSH may report a host key mismatch. This is expected because the device has generated a new SSH key.

To remove the outdated key, run:

ssh-keygen -R 192.168.1.101

Then reconnect:

ssh [email protected]

and accept the new host key when prompted.

When using marcos_install.sh, outdated SSH keys are removed automatically during the installation process. Otherwise, remove the old entry from ~/.ssh/known_hosts and reconnect.

Troubleshooting

  • Verify that the Ethernet cable is properly connected.

  • Confirm that the host computer Ethernet interface is configured with the static IP address 192.168.1.100.

  • Wait a few moments after powering on the Red Pitaya, especially after a fresh installation, as the first boot may take longer than subsequent boots.

  • If the connection still fails, try:

    ping 192.168.1.101

    to verify network connectivity.

Once communication is established, the MaRCoS client and server are ready to be used with MaRGE.