Homework Guidelines: ME495 Embedded Systems in Robotics

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.
   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/${repository}.
   • There should be no files from outside the src/ space. This means that ws and ws/src should not be part of the git repository.
6. Refer to the Git Book and Git Intro for more information on how to use git

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 do I need to do to run the code, assuming the user already understands ROS?
      • Generally, this consists 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?
3. Filenames are case sensitive in Linux. This means that variations such as readme.md, README.MD will not be accepted

If you use any external source (a website or a book, another person, or an LLM or other AI tool such as ChatGPT or Github Copilot), you must cite the source.

1. Create a citations.txt file in the base directory of your repository.
2. The first line in citations.txt should state who you worked with generally, even if no specific code can be traced back to an individual.
3. The subsequent lines should be labeled with a number that can be referred to in source code. Any source code copied, adapted, or inspired by an external source should cross-reference that source in the citations.txt.

Exceptions to this rule hold for me, my notes, and anything under https://docs.ros.org/en/iron/Tutorials.html, and any ROS 2 or package-related "boilerplate" code (that is code that is necessary for the use of the package/feature that would not vary significantly between different uses).

There are additional rules for AI tools:

1. If your use of the LLM is external to your text editor (e.g., you use a website) you must provide a transcript of the conversation in your git repository and refer to it in the citation.
2. If the LLM is built-in to your code editor and uses the context of the editor, then prior to generating the code you must commit your code and record the hash of the commit in the citations.txt.
3. Each individual use of an LLM must be cited.

Here is an example citations.txt: yours should follow the same format.

Worked With: [List every person you worked with generally here.]
[1] Github Copilot. Used on 9/21/2023. Commit prior to use is 3fd56754423456434233242
[2] ChatGpt. Used on 9/22/2023. Transcript is in ./chatgpt/transcript1.txt
[3] https://stackoverflow.com/the/answer Accessed on 9/23/22
[4] John Smith [if John Smith gave you a specific idea outside of generally working with you].

And here is an example of a python file that used a citation

import rclpy

############################## Begin_Citation [4] ##############################
print("Hello please cite me")
rclpy.spin()
############################## End_Citation [4]  ###############################

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. Be sure to follow the docstring conventions.

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.
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
6. 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.