robocup-software
robocup-software copied to clipboard
RoboJackets
Add tutorial project 22-23'
Description
New SW tutorial. Currently intended to go with general SW training--RC members will be expected to watch the video lectures, for their general understanding of robotics topics, ROS, and C++, but to do this tutorial instead of completing the general coding SW tutorial.
Updated docs can be viewed here (open in incognito to avoid caching issues): https://rj-rc-software.readthedocs.io/en/tutorial-project/
@p-nayak11 some thoughts. ~I think we should make this section a bit easier on them. I think I would've quit RoboCup if I was expected to learn C++, CMake, and ROS all at once. Maybe giving them an empty .cpp and .hpp file to copy-paste that just has all the boiler plate code done already--so hpp includes the right ROS stuff, .cpp includes the hpp, constructor is there already and pulls from rclcpp::Node, but the rest of it is up to them.~
EDIT: upon further discussion in Slack, we have agreed that the difficulty is fine and we can always give hints/boilerplate if needed later. You can ignore the difficulty-related comments below.
Also, do you mind wrapping the lines of the .rst source files to 80 chars? That way it's a little easier to edit in the future. This is a VS code extensionthat does it for you (or
gq<motion>in Vim).
This is so weird... I thought that all of the stuff that I added are automatically wrapped because of the settings that I have. For some of the lists, I guess it didn't work.
The tutorial overall looks great. Here's a couple things I'd suggest adding to hopefully reduce the number of repetitive/simple questions we get from new members:
A link to our page on how to source the stack (the software repo README) or a hint for if they get an error related to sourcing That is something that's easy to forget to do (and even easier to fix), but it'll likely prevent existing members from being swarmed by new people asking what's wrong when they don't source ROS (like when using the CLI tools in section 4) because it doesn't explicitly say to do so anywhere. I know the ROS tutorials mention this, but members may leave off in the middle of something or forget what resources are the best to check to remember how to do so, and if we leave a helpful link, it would probably be good.
Reminders to test/run the sim when members write their play in section 3 It seems a bit like a "duh" thing they should know how to do, but they may not think about it and feel slightly hesitant if they don't remember the exact process to launch it. This would hopefully get them used to the usual workflow when working on gameplay/UI stuff (type things, rebuild if applicable, launch sim and check the robot behavior) more quickly. I feel like this would be a second useful place to remind them of the sourcing process.
Additional headers in section 6 (C++ and ROS) It's a long section, and people will likely take multiple meetings to get through both the node and CMakeLists.txt writing process. Not sure if the formatting style we are using for ReadTheDocs allows it, but I think it would help break up the long wall of (useful) text.
I'm happy to add anything above, so let me know if you think these are good ideas!
The tutorial overall looks great. Here's a couple things I'd suggest adding to hopefully reduce the number of repetitive/simple questions we get from new members:
A link to our page on how to source the stack (the software repo README) or a hint for if they get an error related to sourcing That is something that's easy to forget to do (and even easier to fix), but it'll likely prevent existing members from being swarmed by new people asking what's wrong when they don't source ROS (like when using the CLI tools in section 4) because it doesn't explicitly say to do so anywhere. I know the ROS tutorials mention this, but members may leave off in the middle of something or forget what resources are the best to check to remember how to do so, and if we leave a helpful link, it would probably be good.
Reminders to test/run the sim when members write their play in section 3 It seems a bit like a "duh" thing they should know how to do, but they may not think about it and feel slightly hesitant if they don't remember the exact process to launch it. This would hopefully get them used to the usual workflow when working on gameplay/UI stuff (type things, rebuild if applicable, launch sim and check the robot behavior) more quickly. I feel like this would be a second useful place to remind them of the sourcing process.
Additional headers in section 6 (C++ and ROS) It's a long section, and people will likely take multiple meetings to get through both the node and CMakeLists.txt writing process. Not sure if the formatting style we are using for ReadTheDocs allows it, but I think it would help break up the long wall of (useful) text.
I'm happy to add anything above, so let me know if you think these are good ideas!
The Getting Started page addressed issues with sourcing and installing our stack. I believe the starting of the tutorial also points them towards it. I also included the FAQ page in the list of options for help with errors and debugging. That solves some common issues with sourcing and whatnot. I added the second and third suggestions in the last commit.
@kasohrab sadly it's not so easy to put video on a static website. Rest assured we will show them fun videos/live robots on day 1.
hey @p-nayak11 , I changed some of your section to make the flow a bit better from previous sections and enforce my internal style (e.g. no bare links, active voice, more references to the concrete SimRadio class). lmk if you disagree with something I changed
and @fourpenny I broke the C++ part into even smaller subsections now, so hopefully it's more readable. agreed that it used to be too long