Merge branch 'quad_sw_development' into 'master'

Create XSDK instructions in markdown to replace PDF

See merge request !17

quad/README.md

@@ -4,15 +4,48 @@ The `quad/` directory contains all code that programs the quadcopter. This
 includes any C libraries we have written, any HDL to program the Zybo on
 the quad, and the XSDK main project that runs on the Zybo.
 
-## Brief Intro
+## Intro
 
-The main quad application is located at `src/quad_app/`.
+There are three main portions to the system that runs the quad
+
+- Quad Hardware
+- Quad Software Drivers
+- Control Loop
+
+
+#### Quad Hardware
+The quad hardware is located at `xsdk_workspace/system_hw_platform`. This
+consists of the vhdl and associated wrapper code that specifies the hardware on
+the FPGA.
+
+Below is a block diagram of the hardware/software implementation:
+
+![image](doc/images/FPGA_Diagram.png)
+
+#### Quad Software Drivers
+The quad software drivers is all of the code that interacts with the sensors of
+ the quad and collects the data for the control loop to use.
+For example receiving coordinates over wifi and  reading measurements from the
+ accelerometer.
 
 To run this application on the Zybo, we need to implement the hardware drivers,
-and provide a `main` function. This is done in `xsdk_workspace/real_quad/src`.
+and provide a `main` function.
+This is done in `xsdk_workspace/real_quad/src` To build the XSDK project,
+refer to the [XSDK instructions](xsdk_workspace/README.md).
+
+We can also run this application on our own laptops for testing.
+We call this implementation the "virtual quad".
+This is modified in `src/virt_quad`.
 
-We can also run this application on our own laptops for testing. We call this
-implementation the "virtual quad". This is done in `src/virt_quad`.
+#### Control Loop
+The control loop is the algorithm that runs within the quad software drivers.
+This code determines what the code should do to keep the quad flying and as
+close to the waypoint
+ as possible.
+
+The main quad control application is located at `src/quad_app/`.
+This entails a group of C and header files that work as drivers/interfaces to
+the various sensors and communications that are on the quad.
 
 ## Building
 
@@ -29,12 +62,9 @@ directories:
 cd src/<project> && make
 ```
 
-**NOTE**: All build artifacts will be placed in `lib` or `bin` (depending on 
+**NOTE**: All build artifacts will be placed in `lib` or `bin` (depending on
 whether it is a library or executable, respectively)
 
-#### XSDK Project (embedded project that runs on the Zybo)
-To build the XSDK project, refer to the [XSDK instructions](xsdk_workspace/README.md).
-
 ## Testing
 
 #### Automated Tests
@@ -46,13 +76,13 @@ make test
 ```
 
 And glad to hear you are interested in writing your own unit tests! Look at the
-[README](src/test/README.md) and examples in our simple testing library at 
+[README](src/test/README.md) and examples in our simple testing library at
 `src/test`.
 
 #### Manually testing the hardware interface
 
 Of course, we cannot run automated tests on code that needs the Zybo. But
-we have manual tests that you can use to test each specific driver in the 
+we have manual tests that you can use to test each specific driver in the
 hardware interface.
 
 Look in `xsdk_workspace/real_quad/src/hw_impl_zybo_tests.c` for instructions.
@@ -65,5 +95,6 @@ Ideally, you would run these tests from the XSDK IDE.
 * [XSDK Instructions](xsdk_workspace/README.md)  
 
 ## Other Documents
+* [Hardware Block Diagram](doc/images/FPGA_Diagram.png)
 * [Zybo Pinout Assignments](doc/zybo_pinout_assignments.md)  
-* [How to use Xilinx software tools](doc/how_to_use_xilinx_tools.pdf)  
+* [How to use Xilinx software tools](doc/how_to_use_XSDK.md)  

quad/doc/how_to_use_XSDK.md

+# How to use XSDK
+
+## Introduction
+
+In this guide we will cover the following topics regarding XSDK:
+- What Is XSDK
+- How to open XSDK
+- How to create a BSP
+- How to create a new application project
+- How to configure JTAG
+- How to launch an Application Project
+- How to boot using an SD card
+
+
+## What is XSDK?
+
+XSDK stands for Xilinx Software Development Kit and it does exactly that.
+It builds the project C files and necessary packages into files that allow the
+ developer to program the Zybo board to whatever he/she desires granted it meets
+ the system constraints.
+
+There are three main things required for a project:
+  1. A system hardware platform (automatically exporting design from XPS)
+  1. A Board Support Package (Contains software functions for interacting with
+    the Processing System controllers i.e. UART and I2C or logic cores on the FPGA)
+  1. An Application Project (A simple hello world, an NES emulator, or something else)
+
+As mentioned above the system_hw_platform is imported for us by XPS when we
+export our bitstream file to the XSDK. We’ll walkthrough the other two items
+as well as programming the FPGA from within the XSDK.
+
+## Opening XSDK
+
+Setting up access to the Xilinx tools is fairly straight forward given the
+machine the user is on. This guide
+will cover three types of machines: Coover 3050-11 and -12 computers
+(highly recommended), ISU’s
+Remote Linux Servers, and a user’s own PC
+
+1.  Coover 3050-11 and -12
+Two machines in the Distributed Sensing and Decision Making Lab (Coover 3050)
+come with the
+tools already installed. However, the following steps need to be taken in
+order to launch the
+program
+    - In a terminal, enter `source /opt/Xilinx/14.7/ISE_DS/settings64.sh`
+    - In terminal type `xsdk &`
+1. ISU Remote Linux Servers (linux-X, research-x.ece.iastate.edu)
+    - `source Xilinx_Tools/setup_scripts/remote_servers/setup.sh`
+    - In terminal type `xsdk &` (Note: these servers are not good for
+      programming the Zybo board when it comes time to launch a program on the board)
+1. User PC
+    Some users may opt to download the Xilinx tools on their own PCs for
+    development, but this is not recommended.
+    - Download the ISE Design Suite [here](https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/design-tools.html) (~6GB)
+    - Run XSDK
+
+
+## Creating a new Board Support Package (bsp)
+
+The BSP package is responsible for grabbing all necessary Xilinx library files
+so they can be called by your program. In other words, it holds the drivers
+necessary to interface with the hardware on the board.   
+  1. Click File and select New->Board Support Package
+  1. In the New Board Support Package Project, enter a project name
+  (system_bsp in the example).  
+  1. Ensure system_hw_platform and ps7_cortexa9_0 are selected in Target Hardware
+  1. Ensure “standalone” is selected.
+  1. Click Finish to create the BSP  
+
+  __IMPORTANT:__ If UART0 is enabled, follow the steps below, otherwise ensure
+   these are set properly anyway.   
+  1. Click on “standalone” and change the
+    value of stdin AND stdout to ps7_uart_1  
+  1. Click OK when done, you should now see the BSP in the project explorer
+
+##  Creating a new Application Project
+Lastly, we have the software program that will run on the board. This is the
+last piece to the Zybo puzzle, and we’re almost there. Projects can be written
+in C or C++, and can use some standard libraries like stdio, stdlib, string,
+and otherse. HOWEVER, some libraries (often from Linux) are not implemented
+(like time.h), and alternate methods must be used for some things an OS would
+normally handle. Hopefully you do not run into these instances.
+(Off topic hint: If you need timing things, check out xtime_l.h)
+1. Click File -> New -> Application Project to open the New Project box  
+1. Enter a project name, and select the “Use existing” radio button for the
+BSP. We want to use our newly created one rather than create one.   
+1. Click next and select a template (Hello World is probably best) and hit Finish
+1. The new project should appear on the Project Explorer. Expand the project,
+src, and open the helloworld.c  
+
+## Configuring JTAG
+
+We now have all the components, we’re now ready to program the board, but wait,
+ we haven’t setup how we’re going to communicate with the board.  You may now
+ plug in the board to the development computer (yours, Coover machine, etc.)
+ Flip the switch to power on the board.  
+
+  1. In the menu bar, click Xilinx Tools -> Configure JTAG
+  1. If the board is plugged into Coover 3050-11,-12 or a personal PC, then use
+   Auto Detect (It is ill-advised to be programming the Zybo board from a remote
+   linux machine at this point)  
+  1. Click OK   
+
+## Launching an Application Project
+With all our pieces ready to go, we can finally program the board and launch
+ our software program.  
+
+_IMPORTANT:_ A COM terminal should be open after the board has been turned on
+AND before launching the program. Either go through Putty on Windows (COMn
+  Baud 115200) or if through a linux machine (sudo screen /dev/ttyUSB1 115200).
+
+1. On the menu bar, click Xilinx Tools -> Program FPGA, and click Program to
+start the process
+1. If the JTAG configurations and setup were correct, the bitstream should
+load onto the board and a blue LED should turn on indicating the board
+is DONE programming.  
+1. With the board program, we can now launch our software, click on the
+Application Project we want to launch and click the Green Play Arrow button
+ to start.  
+1. View the data received from the board through the COM terminal.
+
+## Booting on SD
+
+The `boot.bin` file is the file that the ZYBO board used on the quad uses to
+produce the hardware platform and run the software for our program to run.
+In a standalone application(no operating system) this should be the only
+file placed on the SD-card.
+### What to Do Before
+
+To correctly make a boot.bin file (using no operating system) you must have
+the following:
+- System hardware platform `.bit` file
+  - Output of hardware toolset (ISE for now)
+  - Path: `MicroCART/quad/xsdk_workspace/sytem_hw_platform/system.bit`
+- Application Project `.elf` file
+  - Be sure to confirm project is built in XSDK
+  - Path: `MicroCART/quad/xsdk_workspace/real_quad/Realease/real_quad.elf`
+- Board Support Package `.elf` file
+  - The current boot loader is a default a standalone for the Zybo board
+  - Be sure to confirm project is built in XSDK
+  - Path: `MicroCART/quad/xsdk_workspace/zybo_fsbl/Realease/zybo_fsbl.elf`
+
+NOTE: None of the `.elf` files are on GIT to reduce clutter
+
+### Instructions
+
+In order to correctly create the boot file you must have all the above files
+updated.
+
+Within XSDK:
+  1. Project -> Create Boot Image. Alternatively right-click on the project in
+  the Project Explorer and -> Create Boot Image  
+  1. Select `MicroCART/quad/xsdk_workspace/zybo_fsbl/Realease/` as the `.bif`
+  1. Click add
+  1. Select `MicroCART/quad/xsdk_workspace/zybo_fsbl/Realease/zybo_fsbl.elf`
+  1. Confirm bootloader is checked and add the file to the Boot Image
+  1. Click add
+  1. Select `MicroCART/quad/xsdk_workspace/sytem_hw_platform/system.bit`
+  1. Add the file to the Boot Image
+  1. Click add
+  1. Select `MicroCART/quad/xsdk_workspace/real_quad/Realease/real_quad.elf`
+  1. Add the file to the Boot Image
+  1. Copy `Boot.bin` file at `MicroCART/quad/xsdk_workspace/zybo_fsbl/Realease/` to SD Card
+  1. Plus SD card into quad and power on board
+
+_NOTE:_ If anything here is unclear there is a deeper explanation in
+[Xilinx: how to create a Boot Image](https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_7/SDK_Doc/tasks/sdk_t_create_zynq_boot_image.htm)
+
+## XSDK Quirks
+
+  The Xilinx SDK has a few quirks that are important to watch out for:
+   - From the [documentation](https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_7/SDK_Doc/tasks/sdk_t_tcf_limitations_faq.htm)
+   , if you abort program execution while at a breakpoint inside an interrupt
+   handler, when re-running the program, interrupts don’t fire. You have to do
+   a hard reset of the board (cycle power) to have interrupts work again.
+   - After doing a `git pull` or `git checkout`, refresh the files by right-
+   clicking on the project in the sidebar and clicking "Refresh"
+   - The project does not detect changes in header files, so if you modify a
+   `.h` file, you should do a clean before re-building, otherwise you may
+   experience unexpected behavior. We got into the habit of always doing a
+   clean before a build whenever creating code that will be put on the quadcopter.

quad/xsdk_workspace/README.md

 # XSDK Workspace
 
-This directory is reserved for XSDK projects.
+This directory is reserved for Xilinx XSDK projects and their respective hardware platforms.  
+
+## What is XSDK
+
+XSDK is a development tool made by Xilinx to create the files necessary to boot
+ the hardware and software on the FPGA. It includes a test editor based on
+ eclipse so the tools should feel vaguely familiar.
+ Use our [how to use XSDK document](../doc/how_to_use_XSDK.md) or 
+ [XSDK documentation webpage](https://www.xilinx.com/support/documentation/sw_manuals/xilinx2015_1/SDK_Doc/index.html)
+
 
 ## Setup
-XSDK, being based on Ecplise, is rather fragile, so do yourself a favor
+XSDK, being based on Eclipse, is rather fragile, so do yourself a favor
 and read this section so things get setup correctly.
 
 1. When you first open eclipse, select this directory, `xsdk_workspace`, as
@@ -13,17 +22,9 @@ and read this section so things get setup correctly.
    add these projects, right-click on the project pane, and click on something
    like "import projects".
 
-  1. Select "Import Existing Projects" (whereever that is)
-  2. And then select the xsd_workspace as the folder where you want to import
+  1. Select "Import Existing Projects" (wherever that is)
+  2. And then select the xsdk_workspace as the folder where you want to import
      projects. Add them all.
 
-3. If things are going swimmingly, then you should be able to build everyhing
+3. If things are going swimmingly, then you should be able to build everything
    and be off on your merry embedded endeavors.
-
-## XSDK FYIs
-Definitely first read the [Xilinx How-To](../doc/how_to_use_xilinx_tools.pdf).
-
-The XIlinx SDK has a few quirks that are important to watch out for:
- 1. From the [documentation](https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_7/SDK_Doc/tasks/sdk_t_tcf_limitations_faq.htm), if you abort program execution while at a breakpoint inside an interrupt handler, when re-running the program, interrupts don’t fire. You have to do a hard reset of the board (cycle power) to have interrupts work again.
- 2. After doing a `git pull` or `git checkout`, refresh the files by right-clicking on the project in the sidebar and clicking "Refresh"
- 3. The project does not detect changes in header files, so if you modify a `.h` file, you should do a clean before re-building, otherwise you may experience unexpected behavior. We got into the habit of always doing a clean before a build whenever creating code that will be put on the quadcopter.

quad/xsdk_workspace/real_quad/README.md

@@ -2,9 +2,9 @@
 _It is real, because it flies._
 
 Welcome to the most lame README in MicroCART. Everything we are about to say
-has already been said elsewhere, including [here][1], [here][2], and [here][3].
+has already been said elsewhere, including [Our quad folder README][1], [xsdk_workspace README][2], and [HOW_TO_USE_XSDK markdown][3].
 So we aren't saying it here. Hence, this README is pretty empty. Hence... lame.
 
 [1]: ../README.md
-[2]: ../../README.md#brief-intro
-[3]: ../../doc/how_to_use_xilinx_tools.pdf
\ No newline at end of file
+[2]: ../../README.md
+[3]: ../../doc/how_to_use_XSDK.md