The SDRLab needs to be connected to power, Ethernet, a gradient DAC board (see Gradient DACs for info), and an RF amplifier/oscilloscope/etc. You’ll need to set up the SDRLab with the FPGA bitstream and MaRCoS server, set up your host to run the MaRCoS client software, and test the system to make sure everything’s fine. Setting the system up will also introduce you to the project structure. Once you have set the system up, you can dive into the using MaRCoS information.

This consists of

• flashing a pre-built Yocto image to an SD card
• preparing a local network
• booting the SDRLab
• Logging into the SDRLab and setting the system time
• Installing the latest FPGA firmware and server
• Running the MaRCoS server
• (Optional) Setting up internet access for the SDRLab

• Blank microSD card, > 2 GiB
• Working Linux environment on your desktop

Note: this is partially adapted from the Raspberry Pi installation guide. If you’re in Windows you can try one of these programs, just make sure to unzip the compressed image first.

Download my compressed SD image; other recent Ocra images (e.g. from Thomas Witzel/Danny Park) should also work. The standard Red Pitaya image also works, and the automated setup script recognises it, but it is not officially supported - use at your own risk (e.g. if you have one lying around).

Note: this is partially adapted from the Download and install SD card image (Windows). Using, for example, the program Win32 Disk Imager, one should follow these steps below:

1. Unzip the compressed image.
2. Insert SD card into your PC or SD card reader.
3. Download Win32 Disk Imager and install it.
4. Right-click on the WinDisk32Imager and select Run as Administrator.
5. Under image file box select unzipped Red Pitaya image file, File type . and select the sdimage-bootpart-202004030120-mmcblk0.direct file (or equivalent).
6. Under device box select the drive letter of the SD card. !!! Be careful to select the correct drive. If you choose the wrong one you risk erasing data from the computer’s hard disk! You can easily see the drive letter (for example E:) by looking in the left column of Windows Explorer.
7. Click Write and wait for the write to complete.
8. Exit the Imager.

Flash it to your SD card, using an SD card reader or similar. In the Linux terminal, I navigate to the image location, then use these commands to extract and write the image:

tar -xvf sdimage-bootpart-202004030120-mmcblk0.direct.tar.bz2
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. Immediately after inserting your SD card, you can find out its device using dmesg | tail in the terminal. BE SURE OF WHAT YOUR SD CARD DEVICE IS, OTHERWISE YOU COULD LOSE DATA ON YOUR HARD DRIVES - CHECK USING GPARTED OR SIMILAR IF YOU’RE UNSURE. This should take around 3 to 5 minutes.

You should receive some info similar to:

1112+1 records in
1112+1 records out
1166386176 bytes (1.2 GB, 1.1 GiB) copied, 101.467 s, 11.5 MB/s

You might want to verify the SD card contents as follows:

sudo dd bs=1M if=/dev/mmcblk0 of=test.img count=1113
sudo truncate --reference sdimage-bootpart-202004030120-mmcblk0.direct test.img
md5sum sdimage-bootpart-202004030120-mmcblk0.direct test.img
sudo rm test.img

where count is based on what the SD-writing dd command showed (1112+1=1113 in the above example).

If the MD5 hashes of the two files are identical, all is well; safely eject the SD card if it’s mounted (note: some Linux environments will have auto-mounted it).

The SDRLab needs an Ethernet LAN to communicate with your PC. Before following these steps, find out whether your institution already provides a way for you to connect new Ethernet devices to your LAN, and what IP address they will be assigned. If you’d rather set up a local network yourself, you’ll need to run a DHCP server on your host PC. Here I describe my test setup, which is just my PC connected to the SDRLab by a direct Ethernet cable.

(Note that it probably won’t work if you have Linux installed in a virtual machine, unless you play around with the network settings in Windows and/or the virtualisation software - please let me know if you’ve gotten this to work successfully.)

In Arch Linux, I’m using =dhcpd= as my server, with the following basic config file (with all comments stripped out):

option domain-name-servers 8.8.8.8, 8.8.4.4;
option subnet-mask 255.255.255.0;
default-lease-time 600;
max-lease-time 7200;
subnet 192.168.1.0 netmask 255.255.255.0 {
  range 192.168.1.100 192.168.1.200;
  option broadcast-address 192.168.1.255;
}

and I start the server when working with the SDRLab using

sudo systemctl start dhcpd4.service

I don’t want the DHCP server running constantly, so when I’m done, I stop it using

sudo systemctl stop dhcpd4.service

or just shut down the PC, since the service is not set to auto-start.

In Ubuntu (Debian) setting the Dhcp changes a little such that the steps are: (from https://linuxhint.com/install_dhcp_server_ubuntu/)

Update the APT package repository cache

$ sudo apt update

Install isc-dhcp-server package

$ sudo apt install isc-dhcp-server

Restart the isc-dhcp-server service

$ sudo systemctl restart isc-dhcp-server

Backup copy of the original configuration file

$ sudo mv -v /etc/dhcp/dhcpd.conf /etc/dhcp/dhcpd.conf.backup

Create a new blank configuration file /etc/dhcp/dhcpd.conf

$ sudo nano /etc/dhcp/dhcpd.conf

Type in the following lines and save the file by pressing <Ctrl> + x followed by y and <Enter>.

option domain-name-servers 8.8.8.8, 8.8.4.4;
option subnet-mask 255.255.255.0;
default-lease-time 600;
max-lease-time 7200;
subnet 192.168.1.0 netmask 255.255.255.0 {
  range 192.168.1.100 192.168.1.200;
  option broadcast-address 192.168.1.255;
}

Restart the isc-dhcp-server

$ sudo systemctl restart isc-dhcp-server

See, the isc-dhcp-server service is running correctly

$ sudo systemctl status isc-dhcp-server

Restart the RP to check if it received the IP as explained in the Arch Linux and also heck that the PC (client) has an IP address in the range of the RP (from 192.168.1.0 to 192.168.1.255).

Open DHCP Server is reported to work, but I haven’t personally tried it. If you have successfully set it up, please update this wiki!

Another option is DHCP Server for Windows, which is user-friendly and also free:

• Download DCHP server for Windows.
• Configure it with the steps found at http://www.dhcpserver.de/cms/running_the_server/

Insert the new SD card, connect the Ethernet, start your DHCP server, and power on the SDRLab. The green LED should turn on immediately, then yellow LEDs will blink randomly for a few seconds. Finally a red LED will blink periodically; this means that the SDRLab is running and has at least mostly booted.

Now you’ll need to see what IP address your DHCP server has assigned to the SDRLab.

-> In Arch Linux, I can do this using

sudo cat /var/lib/dhcp/dhcpd.leases

and the most recent timestamp is probably for your SDRLab.

E.g. the relevant lease in my case is

lease 192.168.1.163 {
starts 6 2020/05/30 14:16:33;
ends 6 2020/05/30 14:26:33;
cltt 6 2020/05/30 14:16:33;
binding state active;
next binding state free;
rewind binding state free;
hardware ethernet 00:26:32:f0:7c:40;
uid "\001\000&2\360|C";
set vendor-class-identifier = "udhcp 1.31.0";
}

so my SDRLab’s IP address is 192.168.1.163 .

If you can’t see a relevant lease in your DHCP server, you didn’t see the same LED pattern, or if this is your first time using a Red Pitaya/SDRLab, you may wish to set up a debug console using the serial port. If there was a problem in any of the steps so far, the console will help you identify what it was.

-> In Windows, assuming you are using DCHP server for Windows, you can go to the trace or open the DHCP status in order to see the assigned IP.

If you have activated the HTTP support as part of step 3 during the DHCP configuration wizard, then you can use your internet browser to open the DHCP status web site: https://127.0.0.1/dhcpstatus.xml. Also easily accessible through the tray icon, right mouse, Open status. This should show the configured and operating connections and also all currently active clients. Once you power on the SDRLab and it is assigned an IP address, it will show up after reloading the page.

Now that you have an IP address, you can SSH into the SDRLab.

In linux, it’s simply ssh [email protected] in my case. The first time you try to connect, you should get a warning about the host’s authenticity - just type yes to proceed if you’re confident you’re not going to be hacked!

In Windows, you may wish to use PuTTY or another SSH client.

On your host (your Linux/Windows desktop PC), run

git clone https://github.com/vnegnev/marcos_extras.git
cd marcos_extras
./marcos_setup.sh IP DEVICE
# example: ./marcos_setup.sh 192.168.1.163 rp-122

where:

• IP is the IP address of your SDRLab.
• DEVICE is your SDRLab hardware, only rp-122 is supported (as of 29/09/2022)

WARNING: if you are running the SDRLab on your institutional network, you should set up a password or other form of login security! Otherwise, automated bots can (and will) log into your SDRLab and mess with it.

Without at least a barebones Linux environment, we can’t give much support - however you can probably use PuTTY/plink to run the steps in marcos_setup.sh manually. These are setting the SDRLab date/time, copying over the latest FPGA bitstream files and loading them, and copying/compiling the MaRCoS server. Please let me know if any of the steps in marcos_setup.sh are unclear.

Note: If you are working in Windows with a Linux virtual machine, the steps in 1.6.a. is perfectly valid for you as well from the virtual machine. They have also been tested in Windows using Git Bash (part of the Git for Windows default installation).

Note: Once the server is in a stable state, a future update to the client will automate this step. Note 2: If you have restarted the RP, you need to run ./load_bitstream.sh 192.168.1.163 (replace with your SDRLab’s IP address). IF YOU START THE SERVER WITHOUT A BITSTREAM, THE SYSTEM WILL CRASH.

On your host, run ssh [email protected] "~/marcos_server" . Keep the terminal open to see diagnostic messages/info. You can close the connection using Ctrl-C, however note that the server will not fully close on the SDRLab. If you want to definitely stop any running instances, use ssh [email protected] "killall marcos_server" beforehand - otherwise, very strange bugs can occur!

It’s convenient to be able to use the Internet from the SDRLab directly, e.g. to work on Git repos. This is easy to set up if you have a Linux host.

I’ve followed the Arch wiki guide to set this up on my host; your distribution may require slightly different steps.

• iptables is installed (your Linux distro may already have it)
• You have an ssh connection open to the SDRLab

enp0s20u3 refers to the external Internet device on the host (in my current setup, it’s a phone tethered to my PC). enp3s0 refers to the Ethernet connection to the SDRLab.

Run the following commands on your host as admin (replacing enp0s20u3 and enp3s0 with your own device names):

sysctl net.ipv4.ip_forward=1
iptables -t nat -A POSTROUTING -o enp0s20u3 -j MASQUERADE
iptables -A FORWARD -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
iptables -A FORWARD -i enp3s0 -o enp0s20u3 -j ACCEPT

You can see the names of your devices using ip link, or ip addr for full address information. Here is the output of ip link on my host, with a SDRLab connected to enp3s0 via DHCP:

[vlad@arch-ssd src]$ ip link
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
 link/ether 08:60:6e:88:c1:35 brd ff:ff:ff:ff:ff:ff
5: enp0s20u3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UNKNOWN mode DEFAULT group default qlen 1000
 link/ether c2:28:9e:c6:6c:94 brd ff:ff:ff:ff:ff:ff

Next, in the SDRLab SSH terminal run:

ip route add 0/0 via 192.168.1.1 dev eth0

To test the connection, run ping www.google.com on the SDRLab. Here’s what mine shows:

root@redpitaya:~# ping -c 4 www.google.com
PING www.google.com (172.217.168.68): 56 data bytes
64 bytes from 172.217.168.68: seq=0 ttl=52 time=198.939 ms
64 bytes from 172.217.168.68: seq=1 ttl=52 time=198.831 ms
64 bytes from 172.217.168.68: seq=2 ttl=52 time=199.641 ms
64 bytes from 172.217.168.68: seq=3 ttl=52 time=200.342 ms

--- www.google.com ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max = 198.831/199.438/200.342 ms

Note: you can automate most of this by following Tutorial 1. This gives you the steps in more detail.

You need to have a reasonably recent version of Python, Numpy and Scipy installed to run the tests.

• Make a new folder somewhere, called marcos. Clone all the repositories in the next steps into it.
• Run git clone https://github.com/lcbMGH/ocra-pulseq.
• Run git clone https://github.com/vnegnev/marcos_client.git -b BRANCH, where BRANCH is master unless you know what you’re doing. Go into the marcos_client directory.
• Duplicate the local_config.py.example file and name the copy local_config.py .
• Fill in your SDRLab’s IP address, the absolute path to the ocra-pulseq library, and all the other parameters in local_config.py .
• Run python test_server.py ; all the tests should pass if it connects correctly and the server is running on the SDRLab. If some tests fail, however, you can still proceed with this guide. Note: Do not worry about the mpack_error_type messages that the server shows; these are deliberate. Note: Several tests will be skipped; this is as intended. If there were no errors, then the system is fine.

If this worked, you can proceed.

This test uses the ocra-pulseq library, written by Lincoln Craven-Brightman at MGH.

Connect an SMA cable from Port 1 of the SDRLab RX to Port 1 of the SDRLab TX (i.e. connect the leftmost to the second-from-rightmost port).

In your marcos_client repo, you should be able to run test_loopback.py. The plot that Python displays should look like [TODO]; if it is significantly different, there may be problems.

You can rerun test_loopback.py and look at your gradient outputs. These should appear roughly as follows for the ocra1 board:

[TODO]

And for the GPA-FHDO:

[TODO]

It’s a good idea to shut down the SDRLab when you’re finished with it, since it gets quite hot during use and this may degrade its lifespan over several years.

You can shut the SDRLab down either in its SSH terminal using poweroff, or running ssh [email protected] "poweroff" (replace with your SDRLab’s IP address) Wait a few seconds after the red light stops flashing, then power off or remove the USB supply.

Warning: Even if you don’t see any harm initially, please avoid powering off the SDRLab without this step! SD card corruption can cause subtle and hard-to-diagnose bugs!