In this tutorial, you’ll set up the MaRCoS software environment, and run the main unit test suite.

Depending on your Linux experience and environment, it will take from 10 minutes to 3 hours – please ask for help if you get stuck.

You should be running an up-to-date desktop version of Linux, either natively, through an emulator or using WSL. I use and enjoy Arch Linux, and run it both natively and under WSL.

You need the following packages. The tutorial has been tested against the versions listed, but earlier versions will probably also work fine. You may, however, need a fairly recent version of Verilator.

• python 3.9.4, scipy 1.6.3, matplotlib 3.4.1, python-msgpack 1.0.2, PyQt5 5.15.4
• Verilator 4.200, Git 2.31, CMake 3.27

You can install them all in Arch Linux with the following terminal command. Depending on your Linux distribution, other dependencies (e.g. GCC) should be installed automatically.

$ sudo pacman -S base-devel python-scipy python-matplotlib python-msgpack verilator cmake

Go to your home folder, and clone the marcos_pack repository:

[vlad@arch-ssd ~]$ cd ~
[vlad@arch-ssd ~]$ git clone https://github.com/vnegnev/marcos_pack.git

Recursively clone the submodule repositories and update them: (NOTE: your commit hashes may not match those below)

[vlad@arch-ssd ~]$ cd marcos_pack/
[vlad@arch-ssd marcos_pack]$ git submodule update --init --recursive
Submodule 'marcos_client' (https://github.com/vnegnev/marcos_client.git) registered for path 'marcos_client'

...... many lines ......

Submodule path 'marga': checked out '9232686e8492be0d700f1a072e5d7caf74cd6547'
[vlad@arch-ssd marcos_pack]$

There are now multiple project folders:

[vlad@arch-ssd marcos_pack]$ ls
marcos_client  marcos_extras  marcos_server  marga

Go into marcos_client, which contains most of the Python scripts you will use to interact with the system, and copy the example local configuration file, local_config.py.example, to create your own:

[vlad@arch-ssd marcos_pack]$ cd marcos_client/
[vlad@arch-ssd marcos_client]$ cp local_config.py.example local_config.py

Open local_config.py in a text editor, and uncomment a few lines (delete the hashes at at the start of the lines) so that the uncommented values are as follows:

ip_address = "localhost"
port = 11111
fpga_clk_freq_MHz = 122.88

grad_board = "gpa-fhdo"

gpa_fhdo_current_per_volt = 2.5

You will adjust the values to suit your hardware in future tutorials.

Now, go to marga and prepare the simulator to be built.

[vlad@arch-ssd marcos_client]$ cd ~/marcos_pack/marga
[vlad@arch-ssd marga]$ mkdir build
[vlad@arch-ssd marga]$ cd build/
[vlad@arch-ssd build]$ cmake ../src/
-- The C compiler identification is GNU 10.2.0
-- The CXX compiler identification is GNU 10.2.0

...... many lines ......

-- Executing Verilator...
-- Configuring done
-- Generating done
-- Build files have been written to: /home/vlad/marcos_pack/marga/build
[vlad@arch-ssd build]$

Return to marcos_client and run the marga unit tests.

[vlad@arch-ssd marcos_client]$ python test_marga_model.py
[  5%] Building CXX object CMakeFiles/marga_sim.dir/marga_sim_main.cpp.o

...... many lines ......

[ 85%] Building CXX object CMakeFiles/marga_sim.dir/usr/share/verilator/include/verilated_threads.cpp.o
[ 90%] Linking CXX executable marga_sim
[100%] Built target marga_sim
.............../mnt/arch_ssd/home/vlad/Documents/mri/marcos_pack/marcos_client/server_comms.py:93: RuntimeWarning: SERVER ERROR: gpa-fhdo gradient error; possibly missing samples
  warnings.warn("SERVER ERROR: " + k, RuntimeWarning)
..................................
----------------------------------------------------------------------
Ran 49 tests in 10.738s

OK
[vlad@arch-ssd marcos_client]$

If you saw the OK message at the end, then congratulations - you have successfully set up the MaRCoS software!

(NOTE: if you saw RuntimeWarning: SERVER ERROR: gpa-fhdo gradient error; possibly missing samples, this is not a problem.)

If any of the dots showed E or F, this means that the selftest failed. See the MaRCoS software debugging guide for some tips.