Skip to content

Setting OCRA up

Jump to bottom
Lincoln Craven-Brightman edited this page Mar 4, 2021 · 11 revisions

Setting OCRA up

Basic requirements:

Hardware

OCRA runs best on a SDRlab 122-16, with additional support for STEMlab 125 versions.

The SDRlab needs to be connected to power, Ethernet, a DAC board, and an RF amplifier/oscilloscope/etc. You’ll need to set up the SDRlab software, set up your host to run the MaRCoS client, and run the server’s unit tests to make sure everything’s fine.

Software

To properly install and run OCRA, you’ll need git, python 3, and a bash terminal. If you’re on Windows, the basic installation of git for windows with git-bash included will cover your git and bash needs. Any installation of python that includes the basic packages like numpy and scipy will be good. Anaconda and WinPython are easy options for this.

Installation steps:

1. Software setup on SDRlab

This consists of

  • Setting up the SDRlab’s disk image on an SD card
  • Connecting your computer to the SDRlab through a direct line or ethernet
  • 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

1.1 SDRlab disk image

To set up the SDRlab’s internal software, you can either use the basic Red Pitaya disk image or the custom pre-built Yocto disk image. Either one needs to be on a microSD card, which the package should include.

Once the microSD card is written, the SDRlab will run whatever is in the microSD slot.

1.2 Connecting to the SDRlab

To connect to the SDRlab, you have a few options

1.6.b. Installing the latest FPGA firmware and server (Windows method)

Without at least a barebones Linux environment, I 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 Vlad 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).

1.7. Running the MaRCoS server (Linux method)

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!

1.8. (Optional) Setting up Internet access for the SDRlab (Linux method)

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.

Prerequisites

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

Commands

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

2. Host setup and unit tests

You need to have a reasonably recent version of Python, Numpy and Scipy installed to run the tests, as well as the Python msgpack library. The scripts will complain if you’re missing something.

[TODO: OLD STUFF – WRITE NEW OCRA-PACK INSTRUCTIONS BELOW]

  • Run git clone --recursive https://github.com/OpenMRI/ocra-pack.git . This will pull in all linked repositories as subfolders of ocra-pack .

In ocra-pack/marcos_client :

  • 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. 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.

3. SDRlab loopback and gradient test

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]

4. Shutting down the SDRlab

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!

Clone this wiki locally