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

Installation for Users

** Prerequisites:**

  1. Ubuntu: The full process was tested in Ubuntu 22.04.5 LTS. Windows users still can install MaRGE, but not set up the marcos server or client following this method. Server and client installation on Windows still follows old method.
  2. Python 3: Ensure you have Python 3 installed on your system.
  3. Empty SD card
  4. Red Pitaya
  5. Internet connection

Installing and Running MaRGE

MaRGE is available on PyPI, so you can easily install it using pip.

Installation

Open a terminal and create a virtual environment in the desired folder. Make sure you have pip installed. Then, run:

pip install marge-mri

Running the GUI

Once installed, you can launch the MaRGE graphical interface from Python:

# Import marge
from marge import main

# Call MaRCoS Graphical Environment (MaRGE)
main.MaRGE()

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/
β”œβ”€β”€ .venv/                         ← optional: virtual environment
β”œβ”€β”€ 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
β”œβ”€β”€ 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.

Configure your hardware

You will need to configure your hardware before continue.

Set up a red pitaya

To configure a new red pitaya, you can execute the marcos_install.sh file as sudo user. This file

sudo ./marcos_install.sh

You can also run this script from the main window clicking in the corresponding button

button

Clicking this button will open a terminal as sudo user, so the password will be required to continue.

The marcos_install.sh script will guide you to 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.