Merged master into workshop2018 to include bjbford work done during H…

…ardware Porting Workshop

README.md

@@ -1,5 +1,17 @@
 # [CASPER Tutorials](http://casper-tutorials.readthedocs.io/en/latest/) [![Documentation Status](https://readthedocs.org/projects/casper-tutorials/badge/?version=latest)](https://casper-tutorials.readthedocs.io/en/latest/?badge=latest) #
 
-This README serves as a short introduction to the tutorials developed by the CASPER Community for newcomers to interfacing with [**CASPER** Hardware](https://casper.berkeley.edu/wiki/Hardware).
+These tutorials serve as an introduction to CASPER's [Toolflow](https://github.com/casper-astro/mlib_devel), [Software](https://github.com/casper-astro/casperfpga), and [Hardware](https://github.com/casper-astro/casper-hardware).
 
-Tutorials are split up into firmware that is developed using either Xilinx's [ISE](https://www.xilinx.com/products/design-tools/ise-design-suite.html) or [Vivado](https://www.xilinx.com/products/design-tools/vivado.html).
+# Downloading
+
+You can download these libraries by cloning this repository and the git submodules within it:
+
+```
+git clone https://github.com/casper-astro/tutorials_devel
+cd tutorials_devel
+git submodule init
+git submodule update
+```
+
+# Documentation
+Documentation for these tutorials can be found [here](https://casper-tutorials.readthedocs.io/)

docs/index.rst

@@ -94,7 +94,7 @@ To use the tutorials you will need to install the versions of Matlab and the Xil
 ============  ==================  ==================
 **Hardware**  **Matlab Version**  **Xilinx Version**
 ============  ==================  ==================
-ROACH1/2      2012b               ISE 14.7 
+ROACH1/2      2013b               ISE 14.7 
 SKARAB        2016b               Vivado 2016.2
 SNAP          2016b               Viviado 2016.4 
 ============  ==================  ================== 

docs/requirements.txt

@@ -1,4 +1,4 @@
 sphinx
 sphinx_rtd_theme
 recommonmark
-sphinx-markdown-tables
+sphinx-markdown-tables==0.0.6

docs/tutorials/roach/tut_intro.md

@@ -248,27 +248,31 @@ Now import the fpga control library. This will automatically pull-in the KATCP l
  import casperfpga
 
 To connect to the board we create a CasperFpga instance; let's call it fpga. The CasperFpga constructor requires just one argument: the IP hostname or address of your FPGA board.
-
- fpga # casperfpga.CasperFpga('roach2 hostname or ip_address')
-
+```python
+fpga = casperfpga.CasperFpga('<roach2 hostname or ip_address>')
+```
 The first thing we do is program the FPGA with the .fpg file which your compile generated.
-
- fpga.upload_to_ram_and_program('your_fpgfile.fpg')
-
+```python
+fpga.upload_to_ram_and_program('<your_fpgfile.fpg>')
+```
 Should the execution of this command return true, you can safely assume the FPGA is now configured with your design. You should see the LED on your board flashing. Go check! All the available/configured registers can be displayed using:
- fpga.listdev()
+```python
+fpga.listdev()
+ ```
 The adder and counter can be controlled by [writing to](https://github.com/ska-sa/casperfpga/wiki/API-Documentation#write_int) and [reading from](https://github.com/ska-sa/casperfpga/wiki/API-Documentation#read_int) registers added in the design using:
- fpga.write_int('a',10)
- fpga.write_int('b',20)
- fpga.read_int('sum_a_b')
 
+```python 
+fpga.write_int('a',10)
+fpga.write_int('b',20)
+fpga.read_int('sum_a_b')
+```
 With any luck, the sum returned by the FPGA should be correct.
 
 You can also try writing to the counter control registers in your design. You should find that with appropriate manipulation of the control register, you can make the counter start, stop, and return to zero.
-
- fpga.write_int('counter_ctrl',10')
- fpga.read_uint('counter_value')
-
+```python
+fpga.write_int('counter_ctrl',10')
+fpga.read_uint('counter_value')
+```
 ## Conclusion
 This concludes the first CASPER Tutorial. You have learned how to construct a simple Simulink design, program an FPGA board and interact with it with Python using [casperfpga](https://github.com/casper-astro/casperfpga). Congratulations!
 

docs/tutorials/snap/tut_intro.md

@@ -252,33 +252,39 @@ As per the previous figure, navigate to the outputs folder and (secure)copy this
 SSH into the server that the SNAP board is connected to and navigate to the folder in which your .fpg file is stored.
 
 Start interactive python by running:
- ipython
-
+```bash
+ipython
+```
 Now import the fpga control library. This will automatically pull-in the KATCP library and any other required communications libraries.
- import casperfpga
-
+```python
+import casperfpga
+```
 To connect to the board we create a CasperFpga instance; let's call it fpga. The CasperFpga constructor requires just one argument: the IP hostname or address of your FPGA board.
-
- fpga # casperfpga.CasperFpga('snap hostname or ip_address')
-
+```python
+fpga = casperfpga.CasperFpga('<snap hostname or ip_address>')
+```
 The first thing we do is program the FPGA with the .fpg file which your compile generated.
 
- fpga.upload_to_ram_and_program('your_fpgfile.fpg')
-
+```python
+fpga.upload_to_ram_and_program('<your_fpgfile.fpg>')
+```
 Should the execution of this command return true, you can safely assume the FPGA is now configured with your design. You should see the LED on your board flashing. Go check! All the available/configured registers can be displayed using:
- fpga.listdev()
+```python
+fpga.listdev()
+```
 The adder and counter can be controlled by [writing to](https://github.com/ska-sa/casperfpga/wiki/API-Documentation#write_int) and [reading from](https://github.com/ska-sa/casperfpga/wiki/API-Documentation#read_int) registers added in the design using:
- fpga.write_int('a',10)
- fpga.write_int('b',20)
- fpga.read_int('sum_a_b')
-
+```python
+fpga.write_int('a',10)
+fpga.write_int('b',20)
+fpga.read_int('sum_a_b')
+```
 With any luck, the sum returned by the FPGA should be correct.
 
 You can also try writing to the counter control registers in your design. You should find that with appropriate manipulation of the control register, you can make the counter start, stop, and return to zero.
-
- fpga.write_int('counter_ctrl',10')
- fpga.read_uint('counter_value')
-
+```python
+fpga.write_int('counter_ctrl',10')
+fpga.read_uint('counter_value')
+```
 ## Conclusion
 This concludes the first CASPER Tutorial. You have learned how to construct a simple Simulink design, program an FPGA board and interact with it with Python using [casperfpga](https://github.com/casper-astro/casperfpga). Congratulations!