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
- Create a git repository using the link provided under the homework assignment in Canvas.
- 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.
- You may use other branches if you wish, but I will only look at the
- 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.
- Maintain a
.gitignore
file to prevent improperly tracked files.- There should be no backup files your text editor created (such as
file.py~
or.#file
or.vscode
). - There should be no python bytecode files (
file.pyc
) committed. (e.g., add__pycache__
to.gitignore
). - There should be no files that are generated form source code that you wrote.
- There should be no backup files your text editor created (such as
- The parent directory of your repository should be
ws/src/${repository}
.- There should be no files from outside the
src/
space. This means thatws
andws/src
should not be part of the git repository.
- There should be no files from outside the
- Refer to the Git Book and Git Intro for more information on how to use
git
README
- 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
orpandoc
to generate.html
from.md
files.
- Your
README.md
should contain the following:- Title
- Your Name
- Brief overview (1-2 sentences) describing what the package does
- 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.
- Generally, these instructions consist of the
- Configuration instructions:
- What options are available to change the behavior of the program or its nodes and how are they used?
- Filenames are case sensitive in Linux. Variations such as
readme.md
,README.MD
will not be accepted.
Citations
- Follow the MSR citations rules.
- Anything under https://nu-msr.github.io/ros_notes or directly linked to by these notes need not be cited.
- Anything under https://docs.ros.org/ need not be cited.
- Anything on https://index.ros.org or provided by the the "API Docs" or "Browse Code" button on that website need not be cited.
- Python API documentation on https://docs.python.org need not be cited.
- All other sources must be cited.
Documentation
- Each node that you write should start with a python docstring describing its ROS API:
- What topics are published, their type, and what they do.
- What topics are subscribed to, their type, and what the data is used for.
- What services are offered, their type, and what they do
- What services are called, their type, and what they do
- What parameters are used, their type, and what they do.
- See https://github.com/m-elwin/crazy_turtle for a basic template.
- Be sure to follow the docstring conventions.
Coding Guidelines
- Strive to follow the PEP8 Style guidelines.
- 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.
- Errors and Warnings should be heeded and fixed.
- In general, refer to
ROS
entities using relative names from within your nodes. - Do not leave debugging statements in code to spew data onto the screen. If the statements may be long-term useful, use
rospy.logdebug
- 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
- Try to narrow down the problem to a self-contained example
- This is especially important when asking for help on internet forums
- 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
- 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
usingrqt_graph
- If the
rosgraph
looks correct, useros2 topic 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.
- Clone your repository into a brand new workspace to make sure you have committed and pushed everything to
git
- Does
colcon build
andcolcon test
run cleanly? - Run the commands in the
README.md
. Do the instructions work? - Are your debugging statements either removed or logged with using ROS logging tools?
- Do your python files have a docstrings explaining the ROS publishers/subscribers/etc…
- Do your functions have docstrings describing the arguments and return types?
- Are there any files (including hidden files) that should be in
.gitignore
but are instead committed?