Skip to content

Commit

Permalink
Merge pull request #31 from moragb96/docs_update
Browse files Browse the repository at this point in the history 
Docs update (round 2)
  • Loading branch information
@jkocz
jkocz committed Jul 16, 2020
2 parents fc993b1 + 48eb429 commit eac2d46
Show file tree
Hide file tree
Showing 4 changed files with 129 additions and 69 deletions.
20 changes: 17 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This README will outline, and make reference to, the following:

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](#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](https://github.com/casper-astro/casperfpga/wiki/Migrating-from-corr-to-casperfpga) for a detailed explanation on **How to migrate to `casperfpga`**.
Should you be an existing `corr` user, wondering where some of your functionality has gone when interfacing to your ROACH/2, please [look here](https://casper-toolflow.readthedocs.io/projects/casperfpga/en/latest/migrating_from_corr.html) for a detailed explanation on **how to migrate to `casperfpga`**.

### Existing Users ###

Expand Down Expand Up @@ -51,6 +51,7 @@ DEBUG:root:casperfpga.casperfpga:roach020203: now a CasperFpga
```shell
$ 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 casperfpga
Expand All @@ -60,23 +61,33 @@ The distribution on the Python Package Index is, of course, a built-distribution

1. Ubuntu 14.04 LTS
2. Ubuntu 16.04 LTS
3. Debian 8.x
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.

```shell
# 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 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.

```shell
$ ipython
```
```python
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](mailto:casper@lists.berkeley.edu), or check the [Mailing List Archive](http://www.mail-archive.com/casper@lists.berkeley.edu/) to see if your issue has been resolved already.
Expand All @@ -98,3 +109,6 @@ fpga.upload_to_ram_and_program('your_file.fpg')
## Contributing ##

Fork [this](https://github.com/casper-astro/casperfpga) repo, add your changes and issue a pull request.

## More documentation ##
A link to `casperfpga` documentation on Read the Docs can be found [here](https://casper-toolflow.readthedocs.io/projects/casperfpga/en/latest/). The documentation there includes the information above, casperfpga sourcecode and links to other CASPER related documentation that may be of interest to users/contributers.
74 changes: 74 additions & 0 deletions docs/How-to-install-casperfpga.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# How to install casperfpga

This section explains how to install `casperfpga`, a python library used to interact with CASPER hardware.

Once you have cloned the casperfpga repository, ensure that you are on the correct branch (usually **master** unless you are a contributor) and always pull regularly to make sure you have the latest version of casperfpga.
almon are considered “anadromous” which means they live in both fresh and salt water. They are born in freshwater where they spend a few months to a few years (depending on the species) before moving out to the ocean
## Installing casperfpga

[`casperfpga`](https://pypi.org/project/casperfpga/) is now available on the Python Package Index (PyPI) and can be installed via [`pip`](https://pip.pypa.io/en/stable/). However, should you need to interface with a SNAP board, your installation workflow involves the extra step of installing against `casperfpga's requirements.txt`.

```shell
$ 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 casperfpga
```

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.

```shell
# 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
```


### Testing that the installation worked

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.

```shell
$ cd ..
$ ipython
```
```python
In [1]: import casperfpga
In [2]: casperfpga.__version__
```

If you receive any errors during this step please feel free to contact anyone on the [CASPER Mailing List](mailto:casper@lists.berkeley.edu), or check the [Mailing List Archive](http://www.mail-archive.com/casper@lists.berkeley.edu/) to see if your issue has been resolved already.

## Using casperfpga

The introductory [tutorials](https://casper-toolflow.readthedocs.io/projects/tutorials/en/latest/) for current CASPER hardware 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:

```python
import casperfpga
fpga = casperfpga.CasperFpga('skarab_host or roach_name')
fpga.upload_to_ram_and_program('your_file.fpg')
```
Once again, please feel free to contact the [CASPER Mailing List](mailto:casper@lists.berkeley.edu) should you encounter any problems or have any questions.

102 changes: 37 additions & 65 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,89 +4,61 @@ casperfpga

Welcome to the documentation for ``casperfpga``, the Python-based communications package for `CASPER Hardware <https://casper.berkeley.edu/wiki/Hardware>`__!

What is casperfpga?
###################
New Users
#########

``casperfpga`` is a Python library used to interact and interface with `CASPER Hardware <https://casper.berkeley.edu/wiki/Hardware>`__. Functionality includes being able to reconfigure firmware, as well as read and write registers across the various communication interfaces. The info here describes the following:

#. :ref:`installation_reference_label`
#. :ref:`usage_reference_label`
#. :ref:`contributing_reference_label`
1. :doc:`Installing casperfpga <How-to-install-casperfpga>`
2. :doc:`Migrating from corr <migrating_from_corr>`
3. :doc:`casperfpga Sourcecode <casperfpga>`

Should you want to dive straight into its usage with `the toolflow proper <https://casper-toolflow.readthedocs.io/en/latest/>`__, `please see here <https://casper.berkeley.edu/wiki/Tutorials>`__.
Should you be an existing `corr` user, wondering where some of your functionality has gone when interfacing to your ROACH/2, `'Migtrating from corr' <https://github.com/casper-astro/casperfpga/wiki/Migrating-from-corr-to-casperfpga>`__ above offers a detailed explanation on how to migrate to ``casperfpga``.

.. _installation_reference_label:
Should you want to dive straight into its usage with `the toolflow proper <https://casper-toolflow.readthedocs.io/en/latest/>`__, `please see here <https://casper-tutorials.readthedocs.io/en/latest/>`__.

Installation
#############
Existing Users
##############

`casperfpga <https://pypi.org/project/casperfpga/>`__ is now available on the Python Package Index (PyPI) and can be installed via `pip <https://pip.pypa.io/en/stable/>`__. However, should you need to interface with a SNAP board, your installation workflow involves the extra step of installing against ``casperfpga's requirements.txt``.

.. code-block:: bash
$ git clone https://github.com/casper-astro/casperfpga
$ cd casperfpga/
$ sudo apt-get install python-pip
$ sudo pip install -r requirements.txt
$ sudo pip install casperfpga
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:

#. Ubuntu 14.04, 16.04 LTS
#. 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.

.. code-block:: bash
$ git clone https://github.com/casper-astro/casperfpga.git
$ cd casperfpga
$ 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.

.. code-block:: bash
$ ipython
From commit `a5e7dcc <https://github.com/ska-sa/casperfpga/tree/a5e7dcc05d4b0234d05e808fc6b8ab91485b8051>`__ and earlier the method of instantiating e.g. a SKARAB object was as follows:

.. code-block:: python
In [1]: import casperfpga
*
If you receive any errors after this please feel free to contact anyone on the `CASPER Mailing List <mailto:casper@lists.berkeley.edu>`_, or check the `Mailing List Archive <http://www.mail-archive.com/casper@lists.berkeley.edu/>`__ to see if your issue has been resolved already.
In [1]: import casperfpga
In [2]: skarab = casperfpga.SkarabFpga('skarab010103')
In [3]: roach = casperfpga.katcp_fpga.KatcpFpga('roach020203')
.. _usage_reference_label:

Usage
#####
The introductory tutorials for `ROACH <https://casper.berkeley.edu/wiki/Introduction_to_Simulink>`__, `ROACH2 <https://casper.berkeley.edu/wiki/Introduction_to_Simulink_ROACH2>`__ and `SKARAB <https://casper.berkeley.edu/wiki/Introduction_to_Simulink_SKARAB>`__ 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 its firmware. Hence the medium of communication is usually done through an ``ipython`` session, as shown below:
As of commit `4adffc0 <https://github.com/ska-sa/casperfpga/commit/4adffc0994c56c38dafe6a395d3ed94e8e9477cc>`__ 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.

.. code-block:: python
import casperfpga
fpga = casperfpga.CasperFpga('skarab_host or roach_name')
fpga.upload_to_ram_and_program('your_file.fpg')
.. _contributing_reference_label:

Contributing
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
Contributing
############

Fork `this <https://github.com/casper-astro/casperfpga>`__ repo, add your changes and issue a pull request.

If you would like to contribute towards this library, fork the casperfpga `repo <https://github.com/casper-astro/casperfpga>`__, add your changes to the fork and issue a pull request to the parent repo.

.. toctree::
:hidden:
:maxdepth: 1
:caption: Documentation
:caption: casperfpga Documentation

How-to-install-casperfpga
migrating_from_corr
casperfpga
casperfpga

.. toctree::
:hidden:
:maxdepth: 1
:caption: Other Documentation

CASPER Documentation <https://casper-toolflow.readthedocs.io/en/latest/>
CASPER Tutorials <http://casper-tutorials.readthedocs.io/en/latest/>
2 changes: 1 addition & 1 deletion docs/migrating_from_corr.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Migrating from `corr`
# Migrating from corr

**So**, you've been using `corr` to communicate and reconfigure your ROACH/2 with .bof files, when suddenly `fpga.progdev('file.bof')` doesn't work anymore. Well, this page aims to help migrate you and your existing system to using casperfpga and use .fpg files to reconfigure your CASPER Hardware.

Expand Down

0 comments on commit eac2d46

Please sign in to comment.