UP | HOME

Homework Guidelines: ME495 Embedded Systems in Robotics

Guidelines

This document describes expectations for homework submissions. You should aim for a professional level of code in all of your homework assignments, which means providing documentation, using git properly, and providing tests where appropriate.

Git

  1. Create a git repository using the link provided under the homework assignment in Canvas.
  2. Your homework will be graded based on what is in the main branch when I clone the repository at some point after the deadline.
    • I recommend working on a separate branch and merging into main when you are ready to submit
  3. You should have multiple commits with meaningful commit messages.
    • There is no exact number of commits you need, it is more about the appropriateness of each commit.
    • Each commit should capture a single "thought" that you coded and tried
    • Bugs will be easier to fix if you make small changes and test them frequently
    • Committing often frees you to experiment while knowing you can always revert the code.
  4. Maintain a .gitignore file to prevent improperly tracked files.
    1. There should be no backup files your text editor created (such as file.py~ or .#file or .vscode).
    2. There should be no python bytecode files (file.pyc) committed.
    3. There should be no files that are generated form source code that you wrote.
  5. The parent directory of your repository should be ws/src/${pkg}.
    • There should be no files from outside the src/ space.
    • src/CMakeLists.txt should not be in the repository (or in the .gitignore since this file is one level above where your repository should be).
  6. Refer to the Git Book and Git Intro for more information on how to use git

README

  1. Your README.md should be formatted using markdown: see this guide.
    • Be sure to format any code using the appropriate code formatting
    • Some text editors like atom or vscode will preview markdown for you locally.
    • You can also use tools like markdown or pandoc to generate .html from .md files.
  2. Your README.md should contain the following:
    1. Title
    2. Your Name
    3. Brief overview (1-2 sentences) describing what the package does
    4. Usage instructions. What do I need to do to run the code, assuming the user already understands ROS?
      • Generally, this consists of the roslaunch command to run and an explanation of its important arguments
    5. Configuration instructions:
      • What options are available to change the behavior of the program and how are they used?

Documentation

  1. Each node that you write should start with a python docstring describing its ROS API:
    1. What topics are published, their type, and what they do.
    2. What topics are subscribed to, their type, and what the data is used for.
    3. What services are offered, their type, and what they do
    4. What parameters are used, their type, and what they do.
    5. See https://github.com/m-elwin/crazy_turtle for a basic template.

Coding Guidelines

  1. Strive to follow the PEP8 Style guidelines.
  2. Every class and function you write should have an associated docstring.
    • A brief description of what the class or function does
    • What the arguments are
    • What the return value is
    • What exceptions may be raised
    • See the Google Python Style Guide (specifically the section on docstrings) for how to format.
    • This format is also described in the Sphinx documentation,
    • Other formats that can be understood by Sphinx are also permissible including NumPy style docstrings or the default reStructured text.
  3. Errors and Warnings should be heeded and fixed
    • Your packages should not have any catkin_lint errors or warnings
  4. In general, refer to ROS entities using relative names from within your nodes.
  5. Do not leave debugging statements in code to spew data onto the screen. If the statements may be long-term useful, use `rospy.logdebug`

Asking For Help

  1. Try to narrow down the problem to a self-contained example
    • This is especially important when asking for help on internet forums
  2. Don't send screenshots for non-graphical items
    • The person helping you can't easily copy and paste text from an image!
    • For small code snippets, include code inline, formatted as code
    • For larger code snippets, provide a link to your github or attach a file
  3. Use the Discussion Forums in Canvas

Tips

  • Read the class notes
  • Read the whole assignment prior to starting
  • Read the documentation on the ROS wiki
  • Read every error message.
  • Draw a diagram of what nodes you expect to run and how they are connected prior to coding
  • Work on a separate branch from main. But keep main up-to-date with working code, as submissions can be constantly updated and improved until I clone them.

  • Before doing any other debugging steps: 

    catkin_make
source devel/setup.bash
    • It never hurts to run these commands again
    • You may have forgotten to, for example, source the workspace in a new terminal window
  • Look at the rosgraph using rqt_graph
  • If the rosgraph looks correct, use rostopic echo to make sure publishers are actually publishing

Checklist

Below is a checklist to use when you are finished and are thinking about turning in your homework.

  1. Is catkin_lint clean (no warnings/errors)?
  2. Does catkin_make finish cleanly (no warnings/errors)?
  3. Run the commands in the README.md. Do the instructions work?
  4. Is package.xml filled in?
  5. Are your debugging statements either removed or logged with rospy.logdebug?
  6. Do your python node files have a docstring at the top explaining the ROS publishers/subscribers/etc…
  7. Do your functions have docstrings describing the arguments and return types?
  8. Clone your repository into a brand new workspace and repeat the checklist.
    • This step ensures you are not missing files in git or relying on some weird state in your current workspace to make everything work

Author: Matthew Elwin.