Merge pull request #27 from BerkeleyLab/doc_revision

Doc revision

Author: smpaiagua

README.md

@@ -1,17 +1,19 @@
 # Marble board
 
-LBNL: Dual FMC (HPC & LPC) NAD Carrier
+Marble is a dual FMC FPGA carrier board developed for general purpose use in particle accelerator electronics instrumentation. It is currently under development and the base platform for two accelerator projects at DOE: ALS-U (the Advanced Light Source Upgrade at LBNL and the LCLS-II HE (the Linac Coherent Light Source II High Energy upgrade).
 
-A general purpose carrier board, sized to satisfy needs of some BPM and LLRF applications
+![marble](docs/marble.jpg)
 
-Status: under development, prototype in testing
+The design responds deployment needs in an accelerator environment: reliability, ability to be remotely programmed, safety watchdog, self monitoring, etc. It is intended to be the base digital design for instrumentation electronics, with the capability of connecting to different I/O or analog front ends through the FMC connectors, and is optimized for cost effectiveness for deployments of hundreds of units. It is based on a Network Attached Device (NAD) approach, where high-speed serial links serve as the communication backbone with other systems in the accelerator.
 
 ## Basic Idea
 
 ![block diagram](docs/block_k3.png)
 
 ## Tools
 
+The Marble design is fully Open Source (licensed under the CERN Open Hardware License v1.2) and designed using Open Source tools (KiCAD).
+
 The schematic/layout tool used is [KiCad EDA](http://www.kicad-pcb.org/)
 version 5.1.8; you can feel comfortable using KiCad version 5.1.x, where x ≥ 5.
 Other versions will very likely either not read the files
@@ -32,10 +34,6 @@ See more comments about KiCad versions in [design/scripts/README.md](design/scri
 * U35: Maxlinear [XRP7724](https://www.maxlinear.com/product/power-management/universal-pmics/universal-pmics/xrp7724) Quad PWM Power Controller
 * Y1: Taitien [TXEAADSANF-25.000000](https://www.taitien.com/wp-content/uploads/2015/12/XO-0076_TX.pdf) 25 MHz VCTCXO
 
-## (Almost) Reality:
-
-![layout](docs/marble_top.png)
-
 ## Auxiliary documentation
 
 25-page schematics like this are a modern reality, but that doesn't mean they
@@ -73,3 +71,9 @@ That's a *different board*: 4xSFP instead of 2xQSFP, and no SO-DIMM socket
 are the most obvious indicators.
 You can go [directly](https://github.com/BerkeleyLab/Marble-Mini/releases/tag/v1.0rc3)
 to the documentation related to that manufacturing run.
+
+## Credits
+
+The initial design is supported by the Berkeley Accelerator Controls and Instrumentation (BACI), a DOE High Energy Physics (HEP) General Accelerator R&D (GARD) program and carried out by the Accelerator Technology Group (ATG) at LBNL, in collaboration with the Warsaw University of Technology (WUT) and Creotech Instruments in Poland.
+
+The board was designed by Michal Gaska (WUT) and Larry Doolittle (LBNL) is the mastermind behind the design. Michael Betz, Vamsi Vytla, Sergio Paiagua and Eric Norum (LBNL) have also contributed to the design and supporting software and firmware throughout the development.

docs/marble.jpg

@@ -0,0 +1,7 @@
+all: Marble_Test_Guide.pdf
+
+%.pdf: %.tex
+	pdflatex -interaction nonstopmode -halt-on-error -file-line-error $<
+
+clean:
+	rm *.pdf

docs/marble_test_guide/Makefile

@@ -7,7 +7,8 @@
 \usepackage{enumitem}
 \usepackage{listings}
 \usepackage[svgnames]{xcolor}
-\usepackage{subfig}
+
+
 
 \setlist{leftmargin=*}
 \usepackage{listings}
@@ -28,11 +29,7 @@
 \graphicspath{{figures/}} %Setting the graphicspath
 \renewcommand\abstractname{Introduction}
 
-
-
-
 \title{Marble -- Factory Acceptance Tests\\ \small{v1.0 2020}}
-\author{Michał Gąska, michalgaska2@gmail.com}
 
 \begin{document}
 
@@ -50,10 +47,10 @@
 
 \clearpage
 
-\section{Overview to Marble module}
+\section{Overview}
 
 \begin{leftbar}
-Design files are open source and can be downolad from Gilhub:
+Design files are open source and can be downloaded from GitHub:
 
 https://github.com/BerkeleyLab/Marble
 \end{leftbar}
@@ -66,26 +63,26 @@ \section{Overview to Marble module}
 \end{leftbar}
 
 \subsection{Hardware requirements}
-To perform all of the tests following hardware are required:
+To perform all tests the following hardware is required:
 \begin{enumerate}
-    \item Lab bench power supply.
-    \item Micro USB calbe.
-    \item QSFP loopback module. 
-    \item FMC Tester module. 
-    \item Multimeter. 
+    \item Lab bench-top power supply.
+    \item Micro USB cable.
+    \item QSFP loopback module.
+    \item FMC Tester module.
+    \item Multimeter.
     \item MMC JTAG (example: SEGGER J-LINK mini).
-    \item FPGA JTAG (example: Digilent JTAG HS3).   
+    \item FPGA JTAG (example: Digilent JTAG HS3).
 \end{enumerate}
 
 \subsection{Software requirements}
-To perform all of the tests following software are required:
+To perform all tests the following software is required:
 \begin{enumerate}
     \item Vivado 19.1.
-    \item Serial port terminal. 
+    \item Serial port terminal.
 \end{enumerate}
 
 \section{Power connection}
-Before connecting the power supply for the first time, check that the main bus is not shorted. Using a multimeter set in resistance measurement mode, measure the resistance between metal pads of the J19 connector (Figure \ref{01}). 
+Before connecting the power supply for the first time, check that the main bus is not shorted. Using a multimeter set in resistance measurement mode, measure the resistance between metal pads of the J19 connector (Figure \ref{01}).
 \begin{figure}[H]
 \begin{center}
 \includegraphics[width=0.9\linewidth]{J19.png}
@@ -96,8 +93,8 @@ \section{Power connection}
 Measured resistance should be around \textbf{{\color{red}200 kOhm}}
 \end{leftbar}
 
-If the resistance is correct, connect the main power. For this purpose, the current limitation on the power supply should be set to 100mA and the voltage to 12V. \textbf{Make sure that the current limit of the laboratory power supply is on.} Now the power cable can be connected to the board and the used laboratory power supply channel can be switched on. 
-This should result in the \textit{12V} LED lighting up as shown  on Figure \ref{02}. Now it is recommended to go to section \nameref{microcontroller}. 
+If the resistance is correct, connect the main power. For this purpose, the current limitation on the power supply should be set to 100mA and the voltage to 12V. \textbf{Make sure that the current limit of the laboratory power supply is on.} Now the power cable can be connected to the board and the used laboratory power supply channel can be switched on.
+This should result in the \textit{12V} LED lighting up as shown  on Figure \ref{02}. Now it is recommended to go to section \nameref{microcontroller}.
 \begin{figure}[H]
 \begin{center}
 \includegraphics[width=0.8\linewidth, angle = 180]{xrpoff.png}
@@ -108,25 +105,25 @@ \section{Power connection}
 \section{Microcontroller programing}
 \label{microcontroller}
 
-Download the latest version of the microcontroller testing code from github:
+Download the latest version of the microcontroller testing code from GitHub:
 \begin{leftbar}
-https://https://gitlab.lbl.gov/spaiagua/marble\_mmc/-/tree/i2c\_rework
+https://gitlab.lbl.gov/spaiagua/marble\_mmc/-/tree/unified\_marble
 \end{leftbar}
 
-A recent version of OpenOCD (v0.10.0 or later) is required. 
+A recent version of OpenOCD (v0.10.0 or later) is required.
 \begin{enumerate}
-	\item Connect JTAG module to \textbf{J14} like it is shown on Figure \ref{23}.
-	\item Connect the micro USB cable and using the serial terminal, connect to the last serial port for the new listed in the operating system. Use 115200 boudrate.
+	\item Connect JTAG module to \textbf{J14} as shown on Figure \ref{23}.
+	\item Connect the micro USB cable and using the serial terminal, connect to the last serial port for the new listed device in the operating system. Use 115200 baudrate.
 	\item Power up the board.
 	\item Program the microcontroller using the following commands:
 	\begin{enumerate}
 	\item Go to the main folder of the downloaded repository.
-	\item Open command terminal and run command:
+	\item From the command line, run the following:
 	\begin{lstlisting}[backgroundcolor = \color{Gainsboro}, language=bash, frame=none]]
 $ make download
 	\end{lstlisting}
 	\end{enumerate}
-	\item After the successful programming, a menu in the serial terminal should appeared and LEDs (LD15, LD11, LD12) should blink in the "snake" pattern.
+	\item After successful programming, a menu in the serial terminal should appear and LEDs (LD15, LD11, LD12) should blink.
 \end{enumerate}
 
 \begin{figure}[H]
@@ -139,7 +136,7 @@ \section{Microcontroller programing}
 
 
 \section{Power Supply programing}
-Before doing the steps below, it is highly recommended to measure if there are no shorts on power rails. Measure resistance between the test points:
+Before doing the steps below it is highly recommended to verify that there are no shorts on the power rails. This can be done by measuring the resistance between the test points:
 
 \begin{enumerate}
     \item \textbf{TP12 (GND)} and \textbf{TP7 (+2V0)}.
@@ -161,15 +158,15 @@ \section{Power Supply programing}
 \end{center}
 \end{figure}
 
-Perform the following steps only and exclusively when there are no shorts on the power rails!
+\textbf{Warning:} Only perform the following steps if there are no shorts on the power rails.
 \begin{enumerate}
-    \item Connect the micro USB cable and using the serial terminal, connect to the last serial port for the new listed in the operating system. Use 115200 boudrate.
-    \item Set up votage to 12V and the current limit to 1A on lab power supply.
+    \item Connect the micro USB cable and, using the serial terminal, connect to the last serial port for the new device listed in the operating system. Use 115200 baudrate.
+    \item Set up voltage to 12V and the current limit to 1A on a lab power supply.
     \item Power up the board.
     \item From the menu displayed in the serial terminal, select the option \menu{g) XRP7724 go}.
-    \item Make a power cycle by turning off and on the lab power supply.
-    \item All power LED indicators should be on (Figure \ref{leds}).
-    \item Using multimeter measure voltage between points:
+    \item Power cycle by turning the lab power supply Off and then On.
+    \item All power LED indicators should be On (Figure \ref{leds}).
+    \item Using multimeter measure the voltage between the test points:
     \begin{enumerate}
     	\item \textbf{TP12 (GND)} and \textbf{TP7 (+2V0)} - expected voltage: +2.0V.
     	\item \textbf{TP12 (GND)} and \textbf{TP9 (+1V0)} - expected voltage: +1.0V.
@@ -192,36 +189,36 @@ \section{Power Supply programing}
 \end{figure}
 
 \section{FPGA programing}
-Download the latest version of the FPGA testing code from github:
+Download the latest version of the FPGA testing code from GitHub:
 \begin{leftbar}
-https://github.com/BerkeleyLab/Bedrock/tree/marblev2
+https://github.com/BerkeleyLab/Bedrock/
 \end{leftbar}
 
 \begin{leftbar}
-Before testing the FPGA it is recommended to set up the current limit to 2A on the lab power supply. 
+Before testing the FPGA it is recommended to set up the current limit to 2A on the lab power supply.
 \end{leftbar}
 \subsection{FMC test}
 \begin{leftbar}
 Board power should be turned off when inserting and removing the FMC module.
 \end{leftbar}
 \begin{enumerate}
-	\item Plug FMC Tester module to one of the FMC connector as it is shown on Figure \ref{fig:example}.
-	\item Connect the micro USB cable and using the serial terminal, connect to the last serial port for the new listed in the operating system. Use 115200 boudrate.
-	\item Change the network adapter settings to connect with static \textbf{192.168.9.10} IP address.
-    \item Connect Marble to the computer using an ethernet cable.
+	\item Plug FMC Tester module to one of the FMC connectors as shown on Figure \ref{fig:example}.
+	\item Connect the micro USB cable and, using the serial terminal, connect to the last serial port for the new device listed in the operating system. Use 115200 baudrate.
+	\item Change the network adapter settings to connect with static IP address \textbf{192.168.9.10}.
+    \item Connect Marble to the computer using an Ethernet cable.
     \item Power up the board.
     \item In the serial terminal menu choose \menu{4) GPIO control
->a) FMC power} to turn on power for FMCs.
+>a) FMC power} to turn on power to the FMCs.
 	\item Program the FPGA using the following steps:
 	\begin{enumerate}
 	\item Go to the folder \textbf{Bedrock/projects/test\_marble\_family/}
-	\item Open command termianal and run command: 
+	\item Open command terminal and run command:
 	\begin{lstlisting}[backgroundcolor = \color{Gainsboro}, language=bash, frame=none]]
 $ mutil usb
 	\end{lstlisting}
 	\end{enumerate}
-	\item To make a test do the following steps:
-	\begin{enumerate}	
+	\item To run a test do the following steps:
+	\begin{enumerate}
 	\item Go to the folder \textbf{Bedrock/projects/test\_marble\_family/}
 	\item To test P1 FMC connector run the following command:
 	\begin{lstlisting}[backgroundcolor = \color{Gainsboro}, language=bash, frame=none]]
@@ -236,13 +233,11 @@ \subsection{FMC test}
 	\end{enumerate}
 \end{enumerate}
 
-\begin{figure}[H]%
-    \centering
-    \subfloat[\centering FMC 1]{{\includegraphics[width=7cm]{fmc1.png} }}%
-    \qquad
-    \subfloat[\centering FMC 2]{{\includegraphics[width=7cm]{fmc2.png} }}%
-    \caption{FMC connectors with plugged FMC Tester board.}%
-    \label{fig:example}%
+\begin{figure}[H]
+\begin{center}
+\includegraphics[width=0.9\linewidth]{fmc_tester.png}
+ \caption{FMC connectors FMC Tester board plugged in.}
+\end{center}
 \end{figure}
 
 \subsection{QSFP test}
@@ -252,18 +247,18 @@ \subsection{QSFP test}
 \end{leftbar}
 \begin{enumerate}
 	\item Plug QSFP loopback module to one of the ports.
-	\item Plug FPGA JTAG module.
+	\item Connect FPGA JTAG programmer.
 	\item Configure FPGA using \texttt{marble\_ibert.bit} bit file.
 	\begin{enumerate}
 		\item Run Vivado
 		\item Go to \menu{Flow>Open Hardware Manager} and then  \menu{Tools>Auto Connect}
-		\item Click \menu{Tools>Program Device>xc7k160t\_0} to open the programming window. 
+		\item Click \menu{Tools>Program Device>xc7k160t\_0} to open the programming window.
 		\item Choose the \textit{bitstream file} and click \menu{Program}
 	\end{enumerate}
-	\item After the successful programming, the Dashboard should start automatically.
+	\item After successful programming, the Dashboard should start automatically.
 	\item Detect links by clicking \menu{Serial I/O Links>Auto-detect links}
-	\item Correct detected and working links should look like in figure \ref{links}.  
-	\item Connect the QSFP loopback module to the other QSFP connector and repeat the above steps.
+	\item Correctly detected and working links should appear as shown in figure \ref{links}.
+	\item Connect the QSFP loopback module to the other QSFP connector and repeat the steps above.
 \end{enumerate}
 
 \begin{figure}[H]
@@ -279,14 +274,14 @@ \subsection{Ethernet test}
     \item Program the FPGA using the following steps:
 	\begin{enumerate}
 	\item Go to the folder \textbf{Bedrock/projects/test\_marble\_family/}
-	\item Open command termianal and run command: 
+	\item Open command terminal and run command:
 	\begin{lstlisting}[backgroundcolor = \color{Gainsboro}, language=bash, frame=none]]
 $ mutil usb
 	\end{lstlisting}
 	\end{enumerate}
-    \item Change the network adapter settings to connect with static \textbf{192.168.9.10} IP address.
-    \item Connect Marble to the computer using an ethernet cable. 
-    \item In Linux command terminal run:
+    \item Change the network adapter settings to connect with static IP address \textbf{192.168.9.10}.
+    \item Connect Marble to the computer using an Ethernet cable.
+    \item Ping the board:
     \begin{lstlisting}[backgroundcolor = \color{Gainsboro}, language=bash, frame=none]]
 $ ping 192.168.9.10
 	\end{lstlisting}
@@ -316,13 +311,9 @@ \subsection{An alternative way to program FPGA}
 \begin{enumerate}
 		\item Run Vivado
 		\item Go to \menu{Flow>Open Hardware Manager} and then  \menu{Tools>Auto Connect}
-		\item Click \menu{Tools>Program Device>xc7k160t\_0} to open the programming window. 
+		\item Click \menu{Tools>Program Device>xc7k160t\_0} to open the programming window.
 		\item Choose the \textit{bitstream file} and click \menu{Program}
 
-	\item After the successful programming, the Dashboard should start automatically.
+	\item After successful programming, the Dashboard should start automatically.
 \end{enumerate}
-\begin{thebibliography}{99}
-%\bibitem{web1} \url{http://bit.ly/PhysLab_Link01}
-%\bibitem{web2} \url{http://bit.ly/PhysLab_Link02}
-\end{thebibliography}
-\end{document}
+\end{document}