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 the code that is in the main branch when I clone the repository at some point after the deadline.
    • You may use other branches if you wish, but I will only look at the main branch.
  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. (e.g., add __pycache__ to .gitignore).
    3. There should be no files that are generated from source code
  5. The parent directory of your repository should be ws/src/${repository}.
    • There should be no files from outside ${repository}, so no ws/src, ws/build, ws/log, or ws/install
  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 vscode 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 does a user need to do to run the code, assuming the user already understands ROS?
      • Generally, these instructions consist of the ros2 launch command to run and an explanation of its important arguments
      • Do not explain how to create a workspace or run colcon build, that is assumed knowledge for a ROS user.
    5. Configuration instructions:
      • What options are available to change the behavior of the program or its nodes and how are they used?
    6. Videos:
      • Any videos that are requested shall be directly embedded in the README.md and must be playable when viewed on the github.com website.
      • To do this, upload the video using a github issue and link to the video on its own line in the README.md
  3. Filenames are case sensitive in Linux. Variations such as readme.md, README.MD will not be accepted.

Citations

  1. Follow the MSR citations rules.
  2. Anything under https://nu-msr.github.io/ros_notes or directly linked to by these notes need not be cited.
  3. Anything under https://docs.ros.org/ need not be cited.
  4. Anything on https://index.ros.org or provided by the the "API Docs" or "Browse Code" button on that website need not be cited.
  5. Python API documentation on https://docs.python.org need not be cited.
  6. All other sources must be cited.
  7. The base directory of your repository shall contain the citations.txt file (case sensitive).
    • Lack of this file is a declaration that you did not work with anybody or consult outside sources.
  8. If applicable, the base directory of your repository shall contain the ai_citations directory with referenced AI generated material

Appropriate Use of Sources

  1. You are expected to use sources to enhance your learning and understanding, as opposed to as a shortcut to copy down solutions
  2. You are responsible for fully understanding all code that is used in your homework solution, even if it is inspired from an external source
    • Lack of understanding of any code can result in a lower grade.
  3. Using a prior student's homework solution or directly "vibe coding" the assignment is against the spirit of the class, is detrimental to learning, and is therefore highly discouraged.

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 services are called, their type, and what they do
    5. What parameters are used, their type, and what they do.
    6. See https://github.com/m-elwin/crazy_turtle for a basic template.
  2. Follow the docstring conventions.
  3. 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.

Coding Guidelines

  1. Strive to follow the PEP8 Style guidelines.
  2. Errors and Warnings should be heeded and fixed.
  3. In general, refer to ROS entities using relative names from within your nodes.
  4. Do not leave debugging statements in code. If the statements may be long-term useful, use rospy.logdebug
  5. Do not use time.sleep() or insert other arbitrary delays in order to make your code work.
    • In most cases (and all cases in the homework) depending on precise delays to make your code work (e.g., to wait for something to finish) is unreliable and dangerous. The time to complete a task may vary between computers or based on different computer usage patterns and therefore sleeping can hide timing bugs.

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. Do not 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, including git README from the project's source code repository.
  • Read every error message.
  • Draw a diagram of what nodes you expect to run and how they are connected prior to coding
  • Commit and push frequently
  • If your work is experimental you can Work on a separate branch from main until it is ready to submit.
  • Look at the rosgraph using rqt_graph
  • If the rosgraph looks correct, use ros2 topic echo to make sure publishers are actually publishing

Final Submission Checklist

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

  1. Clone your repository into a brand new workspace to make sure you have committed and pushed everything to git
  2. Do colcon build and colcon test run cleanly?
    • To be extra safe run colcon build --executor sequential ensuring that there are no race conditions related to parallel dependencies in the build.
  3. Run the commands in the README.md. Do the instructions work?
  4. Are your debugging statements either removed or logged with using ROS logging tools?
  5. Do your python files have a docstrings explaining the ROS publishers/subscribers/etc…
  6. Do your functions have docstrings describing the arguments and return types?
  7. Have the package.xml and setup.py been updated and are they consistent?
  8. Are there any files (including hidden files) that should be in .gitignore but are instead committed?
  9. Ensure that there are no hard-coded paths that are specific to your machine in the source code or configuration files

Author: Matthew Elwin.