major update to docs

- Added complete project management page
- Added ground rules
- Changed documentation to helpful resources
- Updates to frank and workstation
- Added placeholders for project development
- Updated index to reflect changes

docs/source/chess-engine.rst

@@ -0,0 +1,6 @@
+************
+Chess Engine
+************
+
+.. note::
+  This page is a placeholder.

docs/source/conf.py

@@ -51,8 +51,8 @@
 
 # General information about the project.
 project = u'DE3-ROB1-CHESS'
-copyright = u'2018, Ben Greenberg'
-author = u'Ben Greenberg'
+copyright = u'2018, Ben Greenberg et al'
+author = u'Anna Bernbaum, Ben Greenberg, Josephine Latreille, Sanish Mistry, Leah Pattison, Paolo Ruegg, Sylvia Zhang'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/source/documentation.rst

@@ -1,15 +1,39 @@
-*************
-Documentation
-*************
+*****************
+Helpful Resources
+*****************
 
-reStructuredText
-================
+GitHub and Git
+==============
+
+* https://guides.github.com
+* Git basics: https://git-scm.com/book/en/v2/Getting-Started-Git-Basics
+* The super simple beginners guide to Git: http://rogerdudler.github.io/git-guide/
+* Guidance to git commands you may need in the command line: https://www.git-tower.com/blog/git-cheat-sheet/
+
+Structuring large Python projects
+=================================
+
+* Python documentation on what package, module, script are: https://docs.python.org/3/tutorial/modules.html
+* Simple example of this structure and how it is documented: https://github.com/brandon-rhodes/sphinx-tutorial/blob/master/triangle-project/trianglelib
+
+Writing Code: Python Conventions & Documentation
+================================================
+
+* Overall guide to documentation in Python http://docs.python-guide.org/en/latest/writing/documentation/
+* The PEP8 on writing your code keeping to convention (supported by PyCharm): https://www.python.org/dev/peps/pep-0008/
+* The PEP257 on documenting your code:  https://www.python.org/dev/peps/pep-0257/
+* Handling errors with exceptions and raising errors: https://docs.python.org/2/tutorial/errors.html
+
+reStructuredText & Sphinx Markup
+================================
 
 The documentation for this project is written in reStructuredText format. To assist this, the following resources should be acknowledged:
 
 * RST Cheatsheet: https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst
 * RST Reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html
-* RST Primer: http://www.sphinx-doc.org/en/stable/rest.html
+* RST Directives: http://docutils.sourceforge.net/docs/ref/rst/directives.html
+* Sphinx's RST Primer: http://www.sphinx-doc.org/en/stable/rest.html
+* Official Sphinx Markup Constructs: http://www.sphinx-doc.org/en/stable/markup/
 
 Sphinx & Read The Docs
 ======================
@@ -19,4 +43,9 @@ The following resources were useful in the setting up of Sphinx and Read The Doc
 * Screencast: https://www.youtube.com/watch?v=oJsUvBQyHBs
 * RTD Guide: https://docs.readthedocs.io/en/latest/getting_started.html
 * Documenting a project with Sphinx (lecture): https://www.youtube.com/watch?v=QNHM7q2hLh8
-* Sphinx markup: http://www.sphinx-doc.org/en/stable/markup/
+
+Differences between Python 2 and Python 3
+=========================================
+
+* http://sebastianraschka.com/Articles/2014_python_2_3_key_diff.html
+* Porting code from Python 2 to Python 3: https://docs.python.org/3/howto/pyporting.html

docs/source/franka.rst

@@ -7,7 +7,7 @@ Starting up the Panda
 
 The Panda arm should be connected to the workshop floor controller and powered up. When booting, the arm LEDs will flash yellow. Once the arm is booted (solid yellow when completed) you should release the brakes by connecting a computer via ethernet to the base of the arm (see image).
 
-.. figure:: franka_wiring_guide_robot_arm.png
+.. figure:: _static/franka_wiring_guide_robot_arm.png
     :align: center
     :figclass: align-center
 
@@ -38,7 +38,7 @@ Networking with Panda
 
 If you now want to use a workstation computer to control the Arm via the FRANKA Control Interface (FCI) libraries, **first ensure you have completed the above steps to unlock the Arm brakes**. Then move the ethernet cable from the base of the Arm, and connect it to the shop floor controller (as seen in image).
 
-.. figure:: franka_wiring_guide_shop_floor.png
+.. figure:: _static/franka_wiring_guide_shop_floor.png
     :align: center
     :figclass: align-center
 
@@ -51,7 +51,7 @@ With the workstation computer connected to the shop floor controller, you must s
 
 =======================  ============  ==============================
 Device                   IP Address    Notes
------------------------  ------------  ------------------------------
+=======================  ============  ==============================
 FRANKA Arm               192.168.1.0   This does not change
 Shop floor (controller)  192.168.0.88  This does not change
 Workstation              192.168.0.77  Should be static (in settings)

docs/source/ground-rules.rst

@@ -0,0 +1,46 @@
+***************************
+DE Programming Ground Rules
+***************************
+
+1. **Always put code on GitHub**, never use Google Drive or direct messaging.
+
+  a. This means when working on a particular function, you will be working in a smaller team and contributing to a particular branch you set up together.
+  b. Working on a branch in a small team (maybe 2-3) requires coordination so that you don’t create conflicts when pushing your changes to the branch.
+  c. Remember to push changes to a branch, AND sync!
+
+2. **When writing Python, keep to the** `PEP8 Python styling guide`_.
+
+   This style guide is usually enabled in PyCharm to help you. This means you get a squiggle and a yellow/brown mark next to a violation (settings are in ``Preferences > Editor > Inspections > Python``).
+   The key takeaways are:
+
+  a. Naming conventions using: ClassNames, function_names, variable_names
+  b. `White space`_ (PyCharm will give you help here)
+  c. Tabs vs Space, PyCharm actually converts the tab key, and 4 spaces, into the same thing by default (so just don’t change this from default values, and you can use either).
+
+3. **Comment your code! Plus see bullet 4.**
+
+  a. This can be in two main forms, inline or block. `Again, keep to PEP8`_ to avoid differences between code. It’s the simplest one to keep to.
+
+4. **Document your code!**
+
+   Use the PEP257 docstring convention and keep to it well - you can read the `short version PEP257`_, or the `complete PEP257`_.
+
+  a. This means that Sphinx (an automatic documentation generator) will work and display things properly.
+  b. `An example of this can be seen on GitHub`_. It has library, modules, and comments.
+
+5. UML Diagrams... USE THEM
+
+6. `Handle errors properly with exceptions`_. If necessary, build your own errors for safety measures and use try..except..raise blocks in your code.
+
+7. Global variables are bad. Functions are better than types. Objects are likely to be better than complex data structures.
+
+8. Avoid ``from X import *`` as much as possible. It’s much better to import a specific function ``from X import Y`` or to use it in context of your code ``import X; X.Y(arg)``. Otherwise we will need to `start handling lists of import names`_.
+
+.. _`PEP8 Python styling guide`: https://www.python.org/dev/peps/pep-0008/
+.. _`White space`: https://www.python.org/dev/peps/pep-0008/#whitespace-in-expressions-and-statements
+.. _`Again, keep to PEP8`: https://www.python.org/dev/peps/pep-0008/#comments
+.. _`short version PEP257`: http://docs.python-guide.org/en/latest/writing/documentation/
+.. _`complete PEP257`: https://www.python.org/dev/peps/pep-0257/
+.. _`An example of this can be seen on GitHub`: https://github.com/brandon-rhodes/sphinx-tutorial/tree/master/triangle-project/trianglelib
+.. _`Handle errors properly with exceptions`: https://docs.python.org/2/tutorial/errors.html
+.. _`start handling lists of import names`: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package

docs/source/index.rst

@@ -3,16 +3,14 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+**********************************
 DE3-ROB1 CHESS Group Documentation
-==================================
+**********************************
 
-| Design Engineering, Imperial College London
-| Robotics 1 Module
-| Chess Project
-|
+About
+=====
 
-Authors:
-~~~~~~~~
+This is the documentation for the group Chess Project for the Robotics 1 module in Design Engineering, Imperial College London, 2018. The authors:
 
 * Anna Bernbaum, anna.bernbaum15@imperial.ac.uk
 * Ben Greenberg, benedict.greenberg15@imperial.ac.uk
@@ -22,6 +20,8 @@ Authors:
 * Paolo Ruegg, paolo.ruegg15@imperial.ac.uk
 * Sylvia Zhang, zixia.zhang15@imperial.ac.uk
 
+Contents
+========
 
 .. toctree::
    :maxdepth: 2
@@ -32,15 +32,18 @@ Authors:
    operating
 
 .. toctree::
-  :maxdepth: 2
-  :caption: Project Management
-
-  documentation
+   :maxdepth: 2
+   :caption: Project Development
 
+   perception
+   chess-engine
+   motion
 
-Indices and tables
-==================
+.. toctree::
+   :maxdepth: 2
+   :caption: Project Management
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   project-proposal
+   project-plan
+   documentation
+   ground-rules

docs/source/motion.rst

@@ -0,0 +1,6 @@
+******
+Motion
+******
+
+.. note::
+  This page is a placeholder.

docs/source/perception.rst

@@ -0,0 +1,6 @@
+**********
+Perception
+**********
+
+.. note::
+  This page is a placeholder.

docs/source/project-plan.rst

@@ -0,0 +1,102 @@
+************
+Project Plan
+************
+
+Requirements
+============
+
+* **Sketch of a scenario:**
+
+.. figure:: _static/scenario_sketch.png
+    :align: center
+    :figclass: align-center
+
+* **Flow chart of the sequence:**
+
+|  1. Starting the game
+|     a. Set up game pieces
+|  2. Playing the game
+|     a. Completing a move
+|     b. Timing the move
+|     c. Removing pieces
+|     d. Replacing pieces
+|  3. Ending the game
+|     a. Relocating pieces to initial positions
+|
+
+Resources
+=========
+
+* **Confirmed:**
+
+  * FRANCA
+  * Chessboard
+  * Chess Pieces (custom to start with)
+  * Camera (RGB-D, MS Kinect?)
+  * Chess clock
+
+* **Maybe:**
+
+  * Sensors for end-effector (force detection, IMU?)
+  * Customised chess board
+
+Work Breakdown Structure
+========================
+
+Each person’s key areas of interest and work division and summarised in the table below:
+
+=====================  =============================  ==================================
+Area of work           Starting teams (lead in bold)  Change in teams
+=====================  =============================  ==================================
+Documentation          **Ben**                        Ben
+Physical build         **Sanish**, Paolo, Anna        *n/a - (expected completed first)*
+Perception             **Leah**, Paolo                Leah, Paolo
+Game Engine            **Josephine**, Ben             *n/a - (expected completed first)*
+Movement               **Anna**, Sanish, Sylvia       Josephine, Anna, Sanish, Sylvia
+Interface/Controller*  Ben                            Ben
+=====================  =============================  ==================================
+
+*\*implemented later on*
+
+Gantt Chart
+===========
+
+The Gantt chart is dynamic and can be viewed here: https://docs.google.com/spreadsheets/d/1-BJZdqYe8wWnCwUJs8sGYKyAoFGYXU7qOBCCHt1B_Ek/edit?usp=sharing
+
+Implementation
+==============
+
+.. figure:: _static/system_diagram.png
+    :align: center
+    :figclass: align-center
+
+The hardware/software/component approaches to this project will be developed out further with modifications to this system diagram. This will come over the next few weeks.
+
+Expected Difficulties
+=====================
+
+.. list-table::
+  :header-rows: 1
+
+  * - Difficulty
+    - Mitigation strategy
+  * - Gripping outsized pieces (e.g. knight)
+    - Standardised grip geometry at the bottom of each piece
+  * - Positional drift of chess pieces
+    - Perception (active) and gripping (passive) system that can mitigate against drift
+  * - Large RGB-D tolerances leading to board misalignment
+    - Maintain fixed board location
+  * - Integrating the game engine with the motion control
+    - Dedicated project director and clear code structure
+  * - Reliably identifying board in a darker environment
+    - Set up lighting rig to illuminate area
+  * - Grid assignment misaligning on boot
+    - Maintain fixed board location
+  * - User does not remember to press chess clock
+    - Time-out beeper, game manual
+
+
+Risk Assessment & Safety Plan
+=============================
+
+In the FRANKA user manual, pages 62-86 describe an extensive risk assessment.

docs/source/project-proposal.rst

@@ -0,0 +1,24 @@
+****************
+Project Proposal
+****************
+
+CHESS - Robotic Arm Playing Board Games
+=======================================
+
+The goal of this project is to program a robotic arm to play board games such as chess. The robot used will most likely be the FRANKA Emika robotic arm (nicknamed “Panda”) as it is more precise in positioning and grasping than DE NIRO. The outcome of the project will be demonstrated by performing a fully autonomous game of chess between a person and the robot. Perception will need to be added such as an RGB-D camera, a webcam, or a laser scanner.
+
+You can see what the robot looks like here: http://www.imperial.ac.uk/robot-intelligence/robots/franka-emika/
+
+The project includes:
+
+1. **Forward and Inverse Kinematics:** To use the 7-dof kinematic model for Cartesian-to-Joint space mapping.
+2. **Redundancy Resolution:** To resolve the 7-dof arm configuration while following a 6-dof hand pose trajectory.
+3. **Perception:** Adding additional sensor for perceiving the environment and all objects of interest. It could be an RGB-D camera, a webcam, or a laser scanner.
+4. **Object detection and recognition:** To identify the chess pieces on the board as targets for the pick-and-place operations.
+5. **Chess playing software:** Finding a suitable implementation of chess playing algorithm and integrating it within the project.
+6. **Motion Planning:** Using OMPL/MoveIt or other motion planning libraries to generate viable collision-free trajectories for executing the movements.
+7. **Motion Control:** To tune a Cartesian impedance controller or other for fast and smooth motion of the arm.
+8. **Hand control:** To control the grasping with the 2 fingers of the hand.
+
+**Equipment:**
+FRANKA Emika (Panda), RGB-D camera, laser scanner, chess board and pieces

docs/source/workstation.rst

@@ -10,7 +10,7 @@ Generally the set up procedure follows the guide provided on the `FRANKA documen
 Requirements for FRANKA Workstation
 ===================================
 
-#. Install the latest version of Ubuntu (may need to partition hard drive; use Boot Camp on Macintosh)
+#. Install the latest version of Ubuntu (may need to partition hard drive)
 #. `Install the realtime kernel patch`_
 #. Once completed, ensure you are running a real-time kernel with ``uname -r``
 #. Install ROS Kinetic