casperfpga

casperfpga is a python library used to interact and interface with CASPER Hardware. Functionality includes being able to reconfigure firmware, as well as read and write registers across the various communication interfaces.

This README will outline, and make reference to, the following:

1. Notes to Users
   1. New Users
   2. Existing Users
2. Installation
3. Usage
   1. Getting Started
   2. Methods and Utilities
4. Contributing

Notes to casperfpga users

New Users

Not much to say to new users except welcome! It goes without saying that once you have cloned this respository you should make sure you're on the correct branch (usually master, unless you're a contributor) and always pull regularly. This, to make sure you have the latest version of casperfpga with the latest features. You can move on straight to Installation.

Should you be an existing corr user, wondering where some of your functionality has gone when interfacing to your ROACH/2, please look here for a detailed explanation on how to migrate to casperfpga.

Existing Users

From commit a5e7dcc and earlier the method of instantiating e.g. a SKARAB object was as follows:

In [1]: import casperfpga
In [2]: skarab = casperfpga.SkarabFpga('skarab010103')
In [3]: roach = casperfpga.katcp_fpga.KatcpFpga('roach020203')

As of commit 4adffc0 the method of instantiating a ROACH or SKARAB was altered to be done intelligently. casperfpga automatically works out whether the hostname given in its instantiation is a ROACH, SKARAB or SNAP board.

In [1]: import casperfpga
In [2]: skarab = casperfpga.CasperFpga('skarab010103')
DEBUG:root:skarab010103 seems to be a SKARAB
INFO:casperfpga.transport_skarab:skarab010103: port(30584) created & connected.
DEBUG:root:casperfpga.casperfpga:skarab010103: now a CasperFpga
In [3]: roach = casperfpga.CasperFpga('roach020203')
DEBUG:root:roach020203 seems to be a ROACH
INFO:casperfpga.transport_katcp:roach020203: port(7147) created and connected.
DEBUG:root:casperfpga.casperfpga:roach020203: now a CasperFpga

Installation

casperfpga is now available on the Python Package Index (PyPI) and can be installed via pip. However, should you need to interface with a SNAP board, your installation workflow involves the extra step of installing against casperfpga's requirements.txt.

$ git clone https://github.com/casper-astro/casperfpga
$ cd casperfpga/
$ git checkout master
$ sudo apt-get install python-pip
$ sudo pip install -r requirements.txt
$ sudo pip install .

The distribution on the Python Package Index is, of course, a built-distribution; this contains an already-compiled version of the SKARAB programming utility progska, written in C. Operating Systems tested using pip install casperfpga include:

1. Ubuntu 14.04 LTS
2. Ubuntu 16.04 LTS
3. Ubuntu 18.04 LTS
4. Debian 8.x

Unfortunately the success of your installation using pip depends on the host OS of the installation, and you might need to rebuild the utility using the C-compiler native to your OS. In short, follow the more traditional method of installing custom Python packages.

# remove current casperfpga install files
$ cd /usr/local/lib/python2.7/dist-packages
$ sudo rm -rf casper*

# clone the repository to your working directory
$ cd /path/to/working/directory
$ git clone https://github.com/casper-astro/casperfpga.git
$ cd casperfpga
$ git checkout master
$ sudo pip install -r requirements.txt
$ sudo python setup.py install

To check that casperfpga has been installed correctly open an ipython session and import casperfpga. To avoid errors, move out of your cloned casperfpga repository directory before doing this test. casperfpga.__version__ will output the build and githash version of your casperfpga library.

$ ipython

In [1]: import casperfpga
In [2]: casperfpga.__version__

If you receive any errors after this please feel free to contact anyone on the CASPER Mailing List, or check the Mailing List Archive to see if your issue has been resolved already.

Usage

The introductory tutorials for ROACH/2, SKARAB and SNAP serve as a guide to the entire process of:

• Creating an FPGA design in Simulink using the CASPER and Xilinx Blocksets
• Building the design using the toolflow, and lastly
• Reconfiguring your CASPER Hardware with the generated .fpg file using casperfpga

casperfpga is written in python and mainly used to communicate with CASPER Hardware and reconfigure it's firmware. Hence the medium of communication is usually done through an ipython session, as shown below:

import casperfpga
fpga = casperfpga.CasperFpga('skarab_host or roach_name')
fpga.upload_to_ram_and_program('your_file.fpg')

Contributing

Fork this repo, add your changes and issue a pull request.

More documentation

A link to casperfpga documentation on Read the Docs can be found here. The documentation there includes the information above, casperfpga sourcecode and links to other CASPER related documentation that may be of interest to users/contributers.