diff --git a/.gitignore b/.gitignore index 639863e..61496b3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ build/ .vscode/ .idea/ +venv/ +.DS_Store \ No newline at end of file diff --git a/Makefile b/Makefile index 7939a15..9164614 100644 --- a/Makefile +++ b/Makefile @@ -214,3 +214,7 @@ pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: rebuild +rebuild: clean html + open build/html/index.html \ No newline at end of file diff --git a/source/3d_simulation.rst b/source/3d_simulation.rst deleted file mode 100644 index 16bae01..0000000 --- a/source/3d_simulation.rst +++ /dev/null @@ -1,264 +0,0 @@ -############# -3D Simulation -############# - - -******** -Overview -******** - -Simulation allows for safe, quick testing of experimental code and settings, -and can help you practice using the code without having to leave your desk. - - -3D Simulation can be used for developing - - Behaviours - - Motion - - Localisation - - Support Tools - -It cannot be used for developing - - Vision - - -.. tip:: - Breaking simulated robots is a lot cheaper than breaking real ones! - -******************** -Installing Simulator -******************** - -Run ``$RUNSWIFT_CHECKOUT_DIR/bin/setup-simulation.sh`` in a terminal. - - -********************* -Running the Simulator -********************* - -Running the simulator (RCSSServer3d) -==================================== - -To start the simulation server, in a new terminal, run ``rcssserver3d`` - -.. note:: - the following errors will show and **can be ignored**. - - :: - - (Light) ERROR: OpenGLServer not found - (Light) ERROR: OpenGLServer not found - (Material2DTexture) ERROR: cannot find TextureServer - (Material2DTexture) ERROR: OpenGLServer not found. - (Material2DTexture) ERROR: cannot find TextureServer - (Material2DTexture) ERROR: OpenGLServer not found. - (Material2DTexture) ERROR: cannot find TextureServer - (Material2DTexture) ERROR: OpenGLServer not found. - (Material2DTexture) ERROR: cannot find TextureServer - (Material2DTexture) ERROR: OpenGLServer not found. - (Material2DTexture) ERROR: cannot find TextureServer - (Material2DTexture) ERROR: OpenGLServer not found. - (Material2DTexture) ERROR: cannot find TextureServer - (Material2DTexture) ERROR: OpenGLServer not found. - (Material2DTexture) ERROR: cannot find TextureServer - (Material2DTexture) ERROR: OpenGLServer not found. - (Material2DTexture) ERROR: cannot find TextureServer - (Material2DTexture) ERROR: OpenGLServer not found. - (Material2DTexture) ERROR: cannot find TextureServer - (Material2DTexture) ERROR: OpenGLServer not found. - (Material2DTexture) ERROR: cannot find TextureServer - (Material2DTexture) ERROR: OpenGLServer not found. - (sparkgui.rb) sparkRegisterMonitorCmdParser TrainerCommandParser - (InputControl) ERROR: no FPSController found at '/usr/scene/camera/physics/controller' - -Running the visualiser (RoboViz) -================================ - -To start the simulator visualier, in a new terminal run ``roboviz.sh``. -A window should pop up, with a soccer field. - -.. note:: - If you run into a ``Exception in thread "main" java.awt.AWTError: Assistive Technology not found: org.GNOME.Accessibility.AtkWrapper`` you may find this helpful: https://askubuntu.com/a/723503 - -Runing simswift (single robot) -============================== - -#. Run ``build-relwithdebinfo-2.1.sh runswift`` in a new terminal - to compile simswift. It is important to close the server and - visualiser, to speed up the compilation. - This step can be skipped if no re-compilation is required. -#. Launch robot by running ``simswift``. - Runswift commandline arguments can be used, such as - ``simswift -T 18 -n 1``. -#. To kill the robot, use Ctrl+C. - - -Running simswift (team) -======================= - -#. ``build-relwithdebinfo-2.1.sh runswift`` to compile. Skip this step if you don't have to - re-build. -#. ``sim_run`` to launch a whole team. This starts five robot agents. -#. ``sim_kill``, to terminate all agents. - - -Running with Offnao -=================== - -#. Run ``simswift`` in a new terminal. In the terminal, look for the following message and take note of the port number - ``rUNSWift running in SIMULATION mode. DO NOT RUN THIS ON A NAO. Listening for Offnao on port 10241.`` -#. Run ``offnao``, and go ``File -> Connect To Nao (Ctrl+N)``. Enter - ``127.0.0.1`` in first textbox, and the port number in the second - textbox. -#. Click on the first textbox, and press ``Enter``. -#. Click on the red circle button at the bottom left of the offnao - window to start recording. - -.. tip:: - The port number is calculated from the team number and player number of the agent. - -Speeding up the server -====================== - -#. Run ``export SPARK_FAST_TIME=true`` in a new terminal. -#. In the same terminal, run ``rcssserver3d``. - This lets the server run as fast as your CPU can handle. - -.. tip:: - Run ``export SPARK_FAST_TIME=false`` to disable the speed-up. - - -******************** -How It Works -******************** - -3D Simulation consists of - - `rcssserver3d`_ - - `simswift`_ - - `RoboViz`_ - -.. figure:: /images/Simulator_Structure.png - - -rcssserver3d -============ - -3D soccer simulation server running on top of simspark -simulation system. Developed by the RoboCup 3D Simulation League. -rUNSWift modifications are made in `rUNSWift's fork `__. -More information can be found at `Simspark Wiki `__. - -simswift -======== - -simswift is the rUNSWift build target on a Linux PC, and is the agent that connects to the simulation server. -Refer to `Collette's (2017) -thesis `_ -for more info. - -RoboViz -======= - -User-friendly visualiser for the simulator. -Provides a graphical interface to interact with the simulator, such as moving the ball and robots. -rUNSWift modifications are made in `rUNSWift's fork `__. -More information can be found at `magmaOffenburg/RoboViz GitHub `__. - - -************** -Making changes -************** - -Recompiling changes -=================== - -SimSpark --------- - -* To re-compile Spark, run ``spark_build`` from anywhere. -* To re-compile rcssserver3d, run ``rcs_build`` from anywhere. - -.. note:: - ``spark_build``, ``rcs_build`` are located in ``simspark/bin/`` - -Pushing changes -=============== - -Making changes to SimSpark / RCSS ---------------------------------- - -#. Gain push access to `rUNSWift's Simspark Fork `_ -#. Create pull request with a branch with changes. - -Making changes to Roboviz -------------------------- - -#. Gain push access to `rUNSWift's RoboViz Fork `_ -#. Create pull request with a branch with changes. - -.. note:: - For GitHub push access, please :ref:`contact` us. - - -********************** -rUNSWift Modifications -********************** - -This is a list of what rUNSWift has modified in the SimSpark and -RoboViz. This list should be kept up to date so we know what to preserve -when incorporating changes made in the original open-source projects. - -SimSpark / RCSS Modifications -============================= - -100FPS ------- - -- To match the speed of the motion of the SoftBank NAO V5, the - simulator's FPS was changed from 50FPS to 100FPS. - -SPARK_FAST_TIME ---------------- - -- This is an environment variable that was added to affect multiple - settings to allow speed-ups in the simulator - -rcssserver3d/bin ----------------- - -- ``rcs_build`` and ``spark_build`` scripts were added in - ``rcssserver3d/bin`` for easy compiling of the simulator. - -Disabling Autoref ------------------ - -- Autoreffing has been disabled, as it is not needed. - -FieldFeatures -------------- - -- A significant modification rUNSWift has made to rcssserver3d, is the - addition of "FieldFeatures" (corners, t-junctions, centre circles, - etc). -- This is a modification to allow the "orientation" of a fieldfeature - to be recognised (such as a corner) by the agent in the simulator -- To view the list of fieldfeatures refer to - ``simspark/rcssserver3d/data/rsg/agent/nao/soccer.rsg`` - -RoboViz Modification List -========================= - -Goal and Penalty Box Size -------------------------- - -- Goal and Penalty Box Size were modified to meet SPL requirements - -************ -Known issues -************ - -* rcssserver3d will sometimes crash, and keep running in the - background. This can happen especially if you disconnect/connect - agents very quickly. When this happens, run the following command: - ``pkill -9 rcssserver3d; rcssserver3d`` -* Some movements such as the getup have not been tuned in the - simulator. diff --git a/source/contact.rst b/source/about/contact.rst similarity index 93% rename from source/contact.rst rename to source/about/contact.rst index 873599a..d7fdf1e 100644 --- a/source/contact.rst +++ b/source/about/contact.rst @@ -1,5 +1,3 @@ -.. _contact: - ####### Contact ####### diff --git a/source/game_videos.md b/source/about/past_teams/game_videos.md similarity index 100% rename from source/game_videos.md rename to source/about/past_teams/game_videos.md diff --git a/source/about/past_teams/index.rst b/source/about/past_teams/index.rst new file mode 100644 index 0000000..3f56bed --- /dev/null +++ b/source/about/past_teams/index.rst @@ -0,0 +1,9 @@ +########## +Past Teams +########## + +.. toctree:: + :maxdepth: 2 + + team_photos + game_videos diff --git a/source/team_photos.rst b/source/about/past_teams/team_photos.rst similarity index 82% rename from source/team_photos.rst rename to source/about/past_teams/team_photos.rst index b200716..7797f45 100644 --- a/source/team_photos.rst +++ b/source/about/past_teams/team_photos.rst @@ -2,9 +2,23 @@ Team Photos ########### -.. dropdown:: 2023 Bordeaux, France +.. dropdown:: 2025 Salvador, Brazil + :open: + + .. image:: /images/2025_team_photo.jpg + +.. dropdown:: RCAP2024 Qingdao, China + :open: + + .. image:: /images/RCAP2024_team_photo.jpg + +.. dropdown:: 2024 Eindhoven, Netherlands :open: + .. image:: /images/2024_team_photo.jpg + +.. dropdown:: 2023 Bordeaux, France + .. image:: /images/2023_team_photo.JPG .. dropdown:: RCAP2023 Tianjin, China diff --git a/source/code_releases_team_reports.rst b/source/about/publications/code_releases_team_reports.rst similarity index 100% rename from source/code_releases_team_reports.rst rename to source/about/publications/code_releases_team_reports.rst diff --git a/source/about/publications/index.rst b/source/about/publications/index.rst new file mode 100644 index 0000000..b541301 --- /dev/null +++ b/source/about/publications/index.rst @@ -0,0 +1,9 @@ +############ +Publications +############ + +.. toctree:: + :maxdepth: 2 + + code_releases_team_reports + past_research diff --git a/source/past_research.rst b/source/about/publications/past_research.rst similarity index 100% rename from source/past_research.rst rename to source/about/publications/past_research.rst diff --git a/source/conf.py b/source/conf.py index 9d8f9e0..7fe8f0d 100644 --- a/source/conf.py +++ b/source/conf.py @@ -19,63 +19,64 @@ # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +# sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx_copybutton', - 'sphinx.ext.githubpages', - 'sphinx_panels', - 'myst_parser' + "sphinx_copybutton", + "sphinx.ext.githubpages", + "sphinx_panels", + "myst_parser", + "sphinx.ext.autosectionlabel", ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: -source_suffix = ['.rst', '.md'] +source_suffix = [".rst", ".md"] # source_suffix = '.rst' # The encoding of source files. -#source_encoding = 'utf-8-sig' +# source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index' +master_doc = "index" # General information about the project. -project = 'RoboCup SPL' -copyright = '2019-2024, rUNSWift' -author = 'rUNSWift, University of NSW' +project = "RoboCup SPL" +copyright = "2019-2024, rUNSWift" +author = "rUNSWift, University of NSW" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '2024' +version = "2024" # The full version, including alpha/beta/rc tags. -release = '2024' +release = "2024" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = 'en' +language = "en" # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -83,27 +84,27 @@ # The reST default role (used for this markup: `text`) to use for all # documents. -#default_role = None +# default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +# modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False +# keep_warnings = False # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -113,31 +114,31 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' +html_theme = "sphinx_rtd_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +# html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +# html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +# html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +# html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = 'images/rUNSWift.gif' +html_logo = "images/rUNSWift.gif" # The name of an image file (relative to this directory) to use as a favicon of # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +# html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -147,131 +148,124 @@ # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. -#html_extra_path = [] +# html_extra_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +# html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +# html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +# html_domain_indices = True # If false, no index is generated. -#html_use_index = True +# html_use_index = True # If true, the index is split into individual pages for each letter. -#html_split_index = False +# html_split_index = False # If true, links to the reST sources are added to the pages. html_show_sourcelink = False # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +# html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. -#html_use_opensearch = '' +# html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# html_file_suffix = None # Language to be used for generating the HTML full-text search index. # Sphinx supports the following languages: # 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' # 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' +# html_search_language = 'en' # A dictionary with options for the search language support, empty by default. # Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} +# html_search_options = {'type': 'default'} # The name of a javascript file (relative to the configuration directory) that # implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' +# html_search_scorer = 'scorer.js' # https://docs.readthedocs.io/en/stable/guides/vcs.html#github html_context = { - "display_github": True, # Integrate GitHub - "github_user": "UNSWComputing", # Username - "github_repo": "rUNSWift-Manual", # Repo name - "github_version": "master", # Version - "conf_py_path": "/source/", # Path in the checkout to the docs root + "display_github": True, # Integrate GitHub + "github_user": "UNSWComputing", # Username + "github_repo": "rUNSWift-Manual", # Repo name + "github_version": "master", # Version + "conf_py_path": "/source/", # Path in the checkout to the docs root } # Output file base name for HTML help builder. -htmlhelp_basename = 'doctutdoc' +htmlhelp_basename = "doctutdoc" # -- Options for LaTeX output --------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', - -# Latex figure (float) alignment -#'figure_align': 'htbp', + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + #'preamble': '', + # Latex figure (float) alignment + #'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'doctut.tex', 'doctut Documentation', - 'rUNSWift', 'manual'), + (master_doc, "doctut.tex", "doctut Documentation", "rUNSWift", "manual"), ] # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +# latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +# latex_use_parts = False # If true, show page references after internal links. -#latex_show_pagerefs = False +# latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +# latex_show_urls = False # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True +# latex_domain_indices = True # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'doctut', 'doctut Documentation', - [author], 1) -] +man_pages = [(master_doc, "doctut", "doctut Documentation", [author], 1)] # If true, show URL addresses after external links. -#man_show_urls = False +# man_show_urls = False # -- Options for Texinfo output ------------------------------------------- @@ -280,19 +274,25 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'doctut', 'doctut Documentation', - author, 'doctut', 'One line description of project.', - 'Miscellaneous'), + ( + master_doc, + "doctut", + "doctut Documentation", + author, + "doctut", + "One line description of project.", + "Miscellaneous", + ), ] # Documents to append as an appendix to all manuals. -#texinfo_appendices = [] +# texinfo_appendices = [] # If false, no module index is generated. -#texinfo_domain_indices = True +# texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' +# texinfo_show_urls = 'footnote' # If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False +# texinfo_no_detailmenu = False diff --git a/source/contributing/gain_push_access_in_runswift_vm.rst b/source/contributing/gain_push_access_in_runswift_vm.rst deleted file mode 100644 index 02d2b33..0000000 --- a/source/contributing/gain_push_access_in_runswift_vm.rst +++ /dev/null @@ -1,7 +0,0 @@ -############################### -Gain Push Access in rUNSWift-VM -############################### - -.. code-block:: bash - - setup-permanent-vm.sh diff --git a/source/contributing/ide_addons.rst b/source/contributing/ide_addons.rst deleted file mode 100644 index 7cd66f1..0000000 --- a/source/contributing/ide_addons.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _ide_addons: - -########## -IDE Addons -########## - -.. toctree:: - vscode_addons diff --git a/source/contributing/index.rst b/source/contributing/index.rst deleted file mode 100644 index ef9d4a0..0000000 --- a/source/contributing/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -############ -Contributing -############ - -.. toctree:: - pc_setup_contributing - ide_addons - vm_image_creation diff --git a/source/contributing/pc_setup_contributing.rst b/source/contributing/pc_setup_contributing.rst deleted file mode 100644 index e7daea3..0000000 --- a/source/contributing/pc_setup_contributing.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. _pc-setup-contributing: - -####################### -PC Setup (Contributing) -####################### - -These are setup instructions for contributing members of the team to setup their PC. - -************* -Getting Linux -************* - -A Linux OS is required to work with the rUNSWift codebase. -`Ubuntu 22.04 LTS amd64 `_ is the recommended OS. -You can either use a virtual machine, or dual boot your computer. - - -**Pick one of the following:** - -.. toctree:: - gain_push_access_in_runswift_vm - pc_setup_virtual_box - pc_setup_dual_boot - pc_setup_wsl - -.. tip:: - Have at least 50GB storage and 4GB RAM. - -.. warning:: - A virtual machine is more likely to experience slowness in compiling and running simulations. - -********************* -Add SSH key to GitHub -********************* - -#. Generating SSH key - #. Open Terminal (Ctrl+Alt+T) - #. Run :code:`ssh-keygen -t ed25519 -C "your_email@example.com"` - #. Hit enter three times -#. Add SSH key to GitHub by following `GitHub Instructions `_ - -****************** -Cloning Repository -****************** - -Run the following commands to clone the rUNSWift repository - -.. code-block:: bash - - $ sudo apt-get install git - $ git clone git@github.com:UNSWComputing/rUNSWift.git rUNSWift - -.. note:: - Your GitHub account must have access to the private rUNSWift repository to be able to clone it. To gain access, please :ref:`contact` us. - -*********************** -Build Environment Setup -*********************** - -Run the following command to setup the build environment. - -.. code-block:: bash - - $ rUNSWift/bin/setup-build.sh - - -.. note:: - For passwords, please :ref:`contact` us. diff --git a/source/contributing/pc_setup_virtual_box.rst b/source/contributing/pc_setup_virtual_box.rst deleted file mode 100644 index f437f1b..0000000 --- a/source/contributing/pc_setup_virtual_box.rst +++ /dev/null @@ -1,68 +0,0 @@ -####################### -VirtualBox Instructions -####################### - -#. Download `Ubuntu Desktop Image `_. -#. Download and Install `VirtualBox `_. -#. New - #. ======= =============== - Name rUNSWift-VM - ------- --------------- - Type Linux - ------- --------------- - Version Ubuntu (64-bit) - ======= =============== - #. Next - #. =========== ====== - Memory Size 4096MB - =========== ====== - - .. tip:: - Memory size of 2GB is a minimum. - Recommendation is half your system memory. - #. Next - #. Create a Virtual Hard Disk now - #. Create - #. Expert Mode - #. ============================= ===================== - File Size 50GB - ----------------------------- --------------------- - Hard disk file Type VDI - ----------------------------- --------------------- - Storage on physical hard disk Dynamically allocated - ============================= ===================== -#. Settings - #. System - * Processor - ============ ====== - Processor(s) 4 CPUs - ============ ====== - - .. tip:: - Maximum 1 CPU per 1.5GB Base Memory - Recommendation is equal to the number of cores on your system. Ignore the 'Invalid settings detected'. - #. Storage - #. Click on *Empty* under *Controller:IDE*. - #. *Attributess* -> *Optical Drive* -> click on the disc icon - #. Choose Virtual Optical Disk File - #. Select downloaded iso file -#. Start - #. English - #. Install Ubuntu - #. Continue (US Keyboard) - #. Continue (Minimal Installation and Download Updates) - #. Install Now (Erase disk) - #. Continue (write changes to disk?) - #. Continue (Sydney) - #. ========= ============= - Your name (your choice) - --------- ------------- - username (your choice) - --------- ------------- - password (your choice) - ========= ============= - - #. Continue - #. Restart Now (after installation is complete) - -Refer to :ref:`setup_network` for bridging the networks between host machine and VM. diff --git a/source/contributing/pc_setup_wsl.rst b/source/contributing/pc_setup_wsl.rst deleted file mode 100644 index 4bf34ba..0000000 --- a/source/contributing/pc_setup_wsl.rst +++ /dev/null @@ -1,15 +0,0 @@ -########################################### -WSL Instructions (Recommended for Windows) -########################################### - -If you work on Windows, using Ubuntu via WSL with Docker would be the simplest way to get up and running. - -1. Install Ubuntu 22.04 from the Microsoft Store: https://www.microsoft.com/store/productId/9PN20MSR04DW?ocid=pdpshare -2. Install Docker Desktop, and ensure you have WSL support enabled: https://docs.docker.com/docker-for-windows/wsl/ -3. Clone the repo, and run ``make build-all``. Everything should just work. - -GUI apps should work out of the box if you're on Windows 11 via Wslg. -Explore running your own X11 server if you have issues with offnao (we have faced some issues around OpenGL in wslg). - -Vcxsrv works great for this purpose. - diff --git a/source/contributing/vm_image_creation.rst b/source/contributing/vm_image_creation.rst deleted file mode 100644 index 3097469..0000000 --- a/source/contributing/vm_image_creation.rst +++ /dev/null @@ -1,107 +0,0 @@ -################# -VM Image Creation -################# - -These are instructions on creating an OVA file to be used in :ref:`pc_setup` for new team members. - -#. Download `Ubuntu Desktop Image `_. - - .. tip:: For a smaller VM, try Alpine Linux, Tiny Core Linux, or Slax 9. (Only Slax 9 has been tested.) -#. Download and Install `VirtualBox `_. -#. New - #. ======= =============== - Name rUNSWift-VM - ------- --------------- - Type Linux - ------- --------------- - Version Ubuntu (64-bit) - ======= =============== - #. Next - #. =========== ====== - Memory Size 4096MB - =========== ====== - - .. tip:: - Memory size of 2GB is a minimum. - Recommendation is half your system memory. - #. Next - #. Create a Virtual Hard Disk now - #. Create - #. Expert Mode - #. ============================= ===================== - File Size 50GB - ----------------------------- --------------------- - Hard disk file Type VDI - ----------------------------- --------------------- - Storage on physical hard disk Dynamically allocated - ============================= ===================== -#. Settings - #. System - * Processor - ============ ====== - Processor(s) 4 CPUs - ============ ====== - - .. tip:: - Maximum 1 CPU per 1.5GB Base Memory - Recommendation is equal to the number of cores on your system. Ignore the 'Invalid settings detected'. - #. Storage - #. Click on *Empty* under *Controller:IDE*. - #. *Attributess* -> *Optical Drive* -> click on the disc icon - #. Choose Virtual Optical Disk File - #. Select downloaded iso file -#. Start - #. English - #. Install Ubuntu - #. Continue (US Keyboard) - #. Continue (Minimal Installation and Download Updates) - #. Install Now (Erase disk) - #. Continue (write changes to disk?) - #. Continue (Sydney) - #. ========= ============= - Your name (your choice) - --------- ------------- - username (your choice) - --------- ------------- - password (your choice) - ========= ============= - - .. tip:: Do not use the standard runswift password - - #. Continue - #. Restart Now (after installation is complete) - -#. Inside the VM, in a terminal, - - .. code-block:: bash - - ZID=your_zid - mkdir -p ~/.ssh - cd ~/.ssh - wget --user=$ZID --ask-password https://www.cse.unsw.edu.au/~robocup/Nao/Downloads/vm-files/.ssh/id_rsa https://www.cse.unsw.edu.au/~robocup/Nao/Downloads/vm-files/.ssh/config - ssh-keygen -p -N '' -f ~/.ssh/id_rsa - # Enter old passphrase: the standard runswift password - sudo apt install git - cd ~ - git clone git@github.com:UNSWComputing/rUNSWift.git rUNSWift - rUNSWift/bin/setup-build.sh - rUNSWift/bin/setup-simulation.sh - rm -rf ~/.ssh/id_rsa - - .. note:: - For passwords, please :ref:`contact` us. - .. note:: - Consider squashing history - .. tip:: - Reduce the VM size by commenting out ctc-2.8, flite, and game controller from source.sh/setup-build.sh if you don't need them - -#. Shutdown the VM -#. Machine -> Export to OCI - #. Uncheck "Write Manifest File" - #. Next - #. Export -#. Upload ova file to server - - .. code-block:: bash - - rsync -aP ~/Documents/runswift-18.04.ova runswift@runswift2.cse.unsw.edu.au:/var/www/html/ diff --git a/source/contributing/vscode_addons.rst b/source/contributing/vscode_addons.rst deleted file mode 100644 index 19c0952..0000000 --- a/source/contributing/vscode_addons.rst +++ /dev/null @@ -1,21 +0,0 @@ -######################### -Visual Studio Code Addons -######################### - -This page has not been completed yet. Please check back later. - -***** -C/C++ -***** - -******* -GitLens -******* - -************************ -EditorConfig for VS Code -************************ - -****** -Python -****** diff --git a/source/debugging/gdb_server.rst b/source/debugging/gdb_server.rst deleted file mode 100644 index b309bec..0000000 --- a/source/debugging/gdb_server.rst +++ /dev/null @@ -1,38 +0,0 @@ -########## -GDB Server -########## - -To run gdb, complete with symbol table for debugging, we need to compile -runswift, configured for GDB, and run a gdb server on the naos. -Fortunately, this is made easy with some simple scripts: - -#. ``build-relwithdebinfo.sh`` Build complete with all debugging information, - ready for gdb -#. ``nao_sync -rg ``. Sync with debugging symbols. -#. ``nao_connect_gdb `` Open ports required for gdb - server and ssh into the nao itself. You are now on the nao. -#. ``runswift_gdbserver`` Start up runswift, but wait for the remote gdb - instance to connect. If you need to restart, you only need to run - this command. -#. In a seperate terminal, run ``nao_remote_gdb`` Start up the remote gdb instance and connect to - the runswift process running on the nao. - -If everything has worked, you should see something like the following: - -:: - - GNU gdb (Ubuntu 7.7.1-0ubuntu5~14.04.2) 7.7.1 - ... - For help, type "help". - Type "apropos word" to search for commands related to "word". - 0xb78d78f0 in ?? () from /lib/ld-linux.so.2 - (gdb) ▯ - -From now on, you can use gdb as normal. Type ``c``/``continue`` to run. - -If you want to make changes, you only need to run steps 1, 2 and 4 (in -the nao terminal) again, unless you've disconnected from the nao. - -It should be noted that this is going to be running much slower than -normal, so any tasks requiring heavy syncing may not work as -anticipated. diff --git a/source/debugging/index.rst b/source/debugging/index.rst deleted file mode 100644 index effe00e..0000000 --- a/source/debugging/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -######### -Debugging -######### - -.. toctree:: - :maxdepth: 1 - - runswift_gdb - gdb_server diff --git a/source/debugging/runswift_gdb.rst b/source/debugging/runswift_gdb.rst deleted file mode 100644 index e18e44e..0000000 --- a/source/debugging/runswift_gdb.rst +++ /dev/null @@ -1,18 +0,0 @@ -############ -runswift_gdb -############ - -GDB can be used to debug the runswift program on the NAO. - -#. Sync with debugging symbols, run ``nao_sync -rg mario``. - - .. note:: - - Replace "mario" with name of your robot - - .. tip:: - - ``-g`` flag uploads debug symbols to the nao - -#. Run ``runswift_gdb`` -#. Use gdb as normal. diff --git a/source/getting_started/setup_and_workspace/contributing.rst b/source/getting_started/setup_and_workspace/contributing.rst new file mode 100644 index 0000000..6d0ae2b --- /dev/null +++ b/source/getting_started/setup_and_workspace/contributing.rst @@ -0,0 +1,20 @@ +############ +Contributing +############ + +1. Follow the setup instructions +2. Add SSH key to github +3. read and follow the style guide +4. read other instructions? + +********************* +Add SSH key to GitHub +********************* + +#. Generating SSH key + #. Open Terminal (Ctrl+Alt+T) + #. Run :code:`ssh-keygen -t ed25519 -C "your_email@example.com"` + #. Hit enter three times +#. Add SSH key to GitHub by following `GitHub Instructions `_ + +some other contributing key info? \ No newline at end of file diff --git a/source/getting_started/setup_and_workspace/index.rst b/source/getting_started/setup_and_workspace/index.rst new file mode 100644 index 0000000..a473939 --- /dev/null +++ b/source/getting_started/setup_and_workspace/index.rst @@ -0,0 +1,11 @@ +################### +Setup and Workspace +################### + +.. toctree:: + :maxdepth: 2 + + pc_setup + contributing + style_guide + working_remotely diff --git a/source/getting_started/setup_and_workspace/pc_setup.rst b/source/getting_started/setup_and_workspace/pc_setup.rst new file mode 100644 index 0000000..16325e9 --- /dev/null +++ b/source/getting_started/setup_and_workspace/pc_setup.rst @@ -0,0 +1,70 @@ +.. _pc-setup: + +######## +PC Setup +######## + +These are setup instructions for contributing members of the team to setup their PC. +We use docker, so it should work on any system that can install docker. If you want, +you can use bare metal ubuntu or a vm but docker is recommended. + +****************** +Cloning Repository +****************** + +Run the following commands to clone the rUNSWift repository + +.. code-block:: bash + + $ sudo apt-get install git + $ git clone git@github.com:UNSWComputing/rUNSWift.git rUNSWift + +.. note:: + Your GitHub account must have access to the private rUNSWift repository to be able to clone it. To gain access, please :ref:`contact` us. + +****** +Docker +****** + +The recommended way of setting everything up is just using the docker image +clone +run ``make dev`` +voila, everything is set up. + +******************* +Docker alternatives +******************* + +Docker is great and runs on all platforms, but we have some instructions TODO +vms work too + +.. toctree:: + pc_setup_dual_boot + pc_setup_linux + pc_setup_wsl + +*********************** +Build Environment Setup +*********************** + +Run the following command to setup the build environment. + +.. code-block:: bash + + $ make setup + + +.. note:: + For passwords, please :ref:`contact` us. + +************ +Dependencies +************ + +We rely on some third party packages, and for more information on how +those work, see those packages themselves. For a complete list of dependencies, +workspace package dependencies are listed in +robot_ws/src/3rdparty/scripts/install-dependencies.sh, workspace dependencies are listed +in the dockerfile and robot dependencies are located in +/firmware/naoimage-snippets. + diff --git a/source/contributing/pc_setup_dual_boot.rst b/source/getting_started/setup_and_workspace/pc_setup_dual_boot.rst similarity index 100% rename from source/contributing/pc_setup_dual_boot.rst rename to source/getting_started/setup_and_workspace/pc_setup_dual_boot.rst diff --git a/source/getting_started/setup_and_workspace/pc_setup_linux.rst b/source/getting_started/setup_and_workspace/pc_setup_linux.rst new file mode 100644 index 0000000..af6cf4a --- /dev/null +++ b/source/getting_started/setup_and_workspace/pc_setup_linux.rst @@ -0,0 +1,17 @@ +************* +Getting Linux +************* + +A Linux OS is required to work with the rUNSWift codebase. +`Ubuntu 22.04 LTS amd64 `_ is the recommended OS. +You can either use a virtual machine, or dual boot your computer. + + +**Pick one of the following:** + + +.. tip:: + Have at least 50GB storage and 4GB RAM. + +.. warning:: + A virtual machine is more likely to experience slowness in compiling and running simulations. \ No newline at end of file diff --git a/source/getting_started/setup_and_workspace/pc_setup_wsl.rst b/source/getting_started/setup_and_workspace/pc_setup_wsl.rst new file mode 100644 index 0000000..14fabd0 --- /dev/null +++ b/source/getting_started/setup_and_workspace/pc_setup_wsl.rst @@ -0,0 +1,24 @@ +################################ +WSL & Ubuntu Native Instructions +################################ + +If you work on Windows, using the rUNSWift Docker image is the simplest way to get up and running. +However, IsaacSim only works with WSL so I've written this for anyone who wants to follow my steps. +This guide is also applicable to anyone not running the Docker image. + + +1. Install Ubuntu 22.04 from the Microsoft Store: https://www.microsoft.com/store/productId/9PN20MSR04DW?ocid=pdpshare +2. Install Docker Desktop, and ensure you have WSL support enabled: https://docs.docker.com/docker-for-windows/wsl/ +3. Clone the repo +4. Run ``make setup`` which installs 3rd party packages +5. Ctrl F the docker file for ``sudo apt install`` and install everything that's in the docker file. All may not be necessary but doing them all will avoid issues later +6. Ctrl F the naoimage-snippets for ``sudo apt install`` and install everything there. Again, not necessary but if you want to simulate the robot, the robots depend on some of these. + +.. note:: + The below steps haven't been tried as of 2025 + +GUI apps should work out of the box if you're on Windows 11 via Wslg. I haven't tested this +Explore running your own X11 server (we have faced some issues around OpenGL in wslg). + +Vcxsrv works great for this purpose. + diff --git a/source/style_guide.rst b/source/getting_started/setup_and_workspace/style_guide.rst similarity index 100% rename from source/style_guide.rst rename to source/getting_started/setup_and_workspace/style_guide.rst diff --git a/source/working_remotely.rst b/source/getting_started/setup_and_workspace/working_remotely.rst similarity index 100% rename from source/working_remotely.rst rename to source/getting_started/setup_and_workspace/working_remotely.rst diff --git a/source/getting_started/tools/foxglove.rst b/source/getting_started/tools/foxglove.rst new file mode 100644 index 0000000..1172ef7 --- /dev/null +++ b/source/getting_started/tools/foxglove.rst @@ -0,0 +1,5 @@ +######## +Foxglove +######## + +we like using foxglove \ No newline at end of file diff --git a/source/getting_started/tools/index.rst b/source/getting_started/tools/index.rst new file mode 100644 index 0000000..252cdc6 --- /dev/null +++ b/source/getting_started/tools/index.rst @@ -0,0 +1,8 @@ +##### +Tools +##### + +.. toctree:: + + foxglove + simulation \ No newline at end of file diff --git a/source/getting_started/tools/simulation.rst b/source/getting_started/tools/simulation.rst new file mode 100644 index 0000000..9bf74cb --- /dev/null +++ b/source/getting_started/tools/simulation.rst @@ -0,0 +1,30 @@ +############# +3D Simulation +############# + + +******** +Overview +******** + +Simulation allows for safe, quick testing of experimental code and settings, +and can help you practice using the code without having to leave your desk. + + +3D Simulation can be used for developing + - Behaviours + - Motion + - Localisation + - Support Tools + +It cannot be used for developing + - Vision + + +.. tip:: + Breaking simulated robots is a lot cheaper than breaking real ones! + +For previous simulator see here: TODO +we haven't got it working with ROS2, but also nobody has tried so give it a go +We kinda tried webots and isaacsim, maybe rviz? + diff --git a/source/getting_started/work_in_progress.rst b/source/getting_started/work_in_progress.rst new file mode 100644 index 0000000..c332f28 --- /dev/null +++ b/source/getting_started/work_in_progress.rst @@ -0,0 +1,31 @@ +################ +Work in Progress +################ + +In 2024, rUNSWift underwent major changes in order to move to an Ubuntu-based +image. In 2025, rUNSWift underwent more major changes and moved to ROS2 Humble. +In 2025, it was announced that the 2026 RoboCup-SPL will be merging with the +RoboCup Humanoid Kids-size League, and almost definitely changing from the NAO +platform. As such, many things weren't fully completed and this page aims to +summarise all of the things that weren't quite finished. + +structure: +We aimed to set up with a desktop_ws for simulators, and other desktop things. It +didn't quite all make it to the same place, and desktop_ws and robot_ws are a bit +jumbled. We also only have a `make build` for robot_ws and nothing for desktop_ws + +ROS2: +we transitioned to ros2 successfully, but nobody was an expert so there's still +some things we didn't touch. Working with components, intra-process communication +and custom RMW are all concepts we haven't touched. We also haven't moved to a +ROS2 like way of config files. + +Threads etc: +In legacy, they locked threads for different tasks. Now that everything runs as +nodes and we didn't have a lot of knowledge or time to test, we haven't quite +settled on the most efficient way to run everything smoothly with regards to threads. + +Shared IDE addons would be good. TODO add 2024 link + +In legacy, gdb was used for debugging. This hasn't been used in some time, and we're +not sure if it's still relevant. TODO: add 2024 link diff --git a/source/getting_started/working_with_the_robot/button_presses.rst b/source/getting_started/working_with_the_robot/button_presses.rst new file mode 100644 index 0000000..8549e88 --- /dev/null +++ b/source/getting_started/working_with_the_robot/button_presses.rst @@ -0,0 +1,25 @@ +.. _button_presses: + +############## +Button Presses +############## + +********************** +Chest Button Interface +********************** + ++------------------+-----------------+-------------------------------------------------------------------------------------------+ +| Button presses | Foot bumper | Action | ++==================+=================+===========================================================================================+ +| 1 | No | As per rules, set the robot to the penalised or unpenalised (playing) state | ++------------------+-----------------+-------------------------------------------------------------------------------------------+ +| hold | No | Shut down | ++------------------+-----------------+-------------------------------------------------------------------------------------------+ +| hold | Yes | Flash various boards, then reboot **not tested for 2025** | ++------------------+-----------------+-------------------------------------------------------------------------------------------+ + +************ +Head sensors +************ + +Holding all 3 head touch sensors for 1 second will stiffen or unstiffen the robot. \ No newline at end of file diff --git a/source/getting_started/working_with_the_robot/connecting_to_the_robot.rst b/source/getting_started/working_with_the_robot/connecting_to_the_robot.rst new file mode 100644 index 0000000..aa4009d --- /dev/null +++ b/source/getting_started/working_with_the_robot/connecting_to_the_robot.rst @@ -0,0 +1,20 @@ +****************************** +Connecting to the robot +****************************** + +.. warning:: + You only have to follow these steps if you have to connect to an actual robot. + +First, run `make update-hosts`. This will update your hosts file with the robot +names in your system so you can ssh with their names rather than their IPs. + +Next, put your ssh key in `image/home/nao/.ssh/authorized_keys`. Then sync with +the robot or flash it (I think? Idk). Idk if our default password is meant to be +public information or not. + +Make sure you're on the same network as the robot and the robot is visible. If +connecting over LAN directly to robot, use 10.1.AA.2XX, where AA is the team code +and XX is any numbers between 0 and 54. For rUNSWift, AA is 18 and we use 2XX because +0 and 1 starting numbers are reserved for the robots. If connecting over wireless +without a router, use 10.0.AA.2XX. If you have a router, DHCP should be fine. +Typically we connect to a robot with ``ssh nao@``. \ No newline at end of file diff --git a/source/game_preparation/calibration/calibration_camera_settings.rst b/source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_camera_settings.rst similarity index 100% rename from source/game_preparation/calibration/calibration_camera_settings.rst rename to source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_camera_settings.rst diff --git a/source/game_preparation/calibration/calibration_getup.rst b/source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_getup.rst similarity index 99% rename from source/game_preparation/calibration/calibration_getup.rst rename to source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_getup.rst index 6934a30..c507dc2 100644 --- a/source/game_preparation/calibration/calibration_getup.rst +++ b/source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_getup.rst @@ -1,6 +1,6 @@ -############### +##### Getup -############### +##### We fall over a lot, so we need to make sure the getup works reliably. diff --git a/source/game_preparation/calibration/calibration_kick.rst b/source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_kick.rst similarity index 100% rename from source/game_preparation/calibration/calibration_kick.rst rename to source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_kick.rst diff --git a/source/game_preparation/calibration/calibration_kinematics.rst b/source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_kinematics.rst similarity index 100% rename from source/game_preparation/calibration/calibration_kinematics.rst rename to source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_kinematics.rst diff --git a/source/game_preparation/calibration/calibration_walk.rst b/source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_walk.rst similarity index 100% rename from source/game_preparation/calibration/calibration_walk.rst rename to source/getting_started/working_with_the_robot/game_preparation/calibration/calibration_walk.rst diff --git a/source/game_preparation/calibration/index.rst b/source/getting_started/working_with_the_robot/game_preparation/calibration/index.rst similarity index 91% rename from source/game_preparation/calibration/index.rst rename to source/getting_started/working_with_the_robot/game_preparation/calibration/index.rst index 3d8445f..d6310c9 100644 --- a/source/game_preparation/calibration/index.rst +++ b/source/getting_started/working_with_the_robot/game_preparation/calibration/index.rst @@ -3,7 +3,7 @@ Robot Calibration ################# .. toctree:: - :maxdepth: 2 + :maxdepth: 1 calibration_camera_settings calibration_kinematics diff --git a/source/game_preparation/index.rst b/source/getting_started/working_with_the_robot/game_preparation/index.rst similarity index 100% rename from source/game_preparation/index.rst rename to source/getting_started/working_with_the_robot/game_preparation/index.rst diff --git a/source/game_preparation/setup_game_script.rst b/source/getting_started/working_with_the_robot/game_preparation/setup_game_script.rst similarity index 100% rename from source/game_preparation/setup_game_script.rst rename to source/getting_started/working_with_the_robot/game_preparation/setup_game_script.rst diff --git a/source/game_preparation/setup_venue_script.rst b/source/getting_started/working_with_the_robot/game_preparation/setup_venue_script.rst similarity index 100% rename from source/game_preparation/setup_venue_script.rst rename to source/getting_started/working_with_the_robot/game_preparation/setup_venue_script.rst diff --git a/source/getting_started/working_with_the_robot/index.rst b/source/getting_started/working_with_the_robot/index.rst new file mode 100644 index 0000000..599901d --- /dev/null +++ b/source/getting_started/working_with_the_robot/index.rst @@ -0,0 +1,15 @@ +###################### +Working with the Robot +###################### + +.. toctree:: + :maxdepth: 3 + + nao_setup + connecting_to_the_robot + running_runswift + game_preparation/index + turning_on + button_presses + leds + networking diff --git a/source/running/leds.rst b/source/getting_started/working_with_the_robot/leds.rst similarity index 100% rename from source/running/leds.rst rename to source/getting_started/working_with_the_robot/leds.rst diff --git a/source/setup/nao_setup.rst b/source/getting_started/working_with_the_robot/nao_setup.rst similarity index 72% rename from source/setup/nao_setup.rst rename to source/getting_started/working_with_the_robot/nao_setup.rst index 360eef1..2f69ccf 100644 --- a/source/setup/nao_setup.rst +++ b/source/getting_started/working_with_the_robot/nao_setup.rst @@ -1,16 +1,17 @@ -################## +######### NAO Setup -################## +######### .. note:: In 2025, rUNSWift completely migrated to `ROS2 Humble `_. If you wish to see the old documentation for the - Ubuntu-based OS visit https://runswift.readthedocs.io/en/2024/setup/nao_setup.html + Ubuntu-based OS visit `the 2024 legacy docs `_, + particularly `the what's different section `_. .. note:: In 2024, rUNSWift completely migrated their robot OS to Ubuntu. If you wish to see the old documentation for the - Softbank-based OS visit https://runswift.readthedocs.io/en/2023/setup/nao_setup.html + Softbank-based OS visit `the 2023 legacy docs `_. In this guide, we will go through the process of setting up a fresh NAO robot for RoboCup SPL using rUNSWift's image. @@ -21,33 +22,70 @@ The robots that return from repair will likely not need these instructions. .. note:: **You do not need to do this if are just setting up your environment!** -***************** -What's different? -***************** -Our robots have traditionally been running NAOqi OS. However, we recently transitioned our robots (and our tooling/software) to be compatible with Ubuntu 22.04 as a base image. - -This offers several advantages. On top of being more familiar to most of us, it makes things a lot simpler from a technical perspective, -alongside allowing us to pursue new technical projects with a better chance of success such as the ongoing research into a migration to ROS/ROS2. *********************** -Build rUNSWift for ROS2 +Compiling for ROS2 *********************** Before doing anything, you should build. While technically optional, this will be useful later on, as the image you create would automatically bake in the executables if they exist. Make sure you follow the PC setup guide beforehand. Use Docker on all platforms except bare metal Ubuntu 22.04. +First launch into Docker, otherwise follow the regular ROS2 steps like `source /opt/ros/humble/setup.bash` + .. code-block:: bash - # Launch into Docker, otherwise follow the regular ROS2 steps like `source /opt/ros/humble/setup.bash` make dev + +Then build + +.. code-block:: bash + + make build + +To build manually + +.. code-block:: bash + cd robot_ws - colcon build + colcon build --cmake-args ' -DCMAKE_BUILD_TYPE=Release' + +.. tip:: + + Optionally, you can also compile just a package using the typical `ROS2 method `_. + + .. code-block:: bash + + cd robot_ws + colcon build --packages-up-to --cmake-args ' -DCMAKE_BUILD_TYPE=Release' + + +.. tip:: + Builds can fail in strange ways sometimes. Try a clean build, building after a ``make clean``. +******* +Syncing +******* -***************** +To sync code, run + +.. code-block:: bash + + make sync + +To sync a specific package, add that package + +.. code-block:: bash + + make sync + +****************** +Building an image +****************** + +~~~~~~~~~~~~~~~~~ Download opn file -***************** +~~~~~~~~~~~~~~~~~ OpenNAO (opn) files are the image file for the NAO robot. @@ -71,9 +109,9 @@ You can download them manually as follows: .. warning:: Due to software licensing between Softbank and RoboCup SPL, teams can't publicly release the NAOqi OS provided by Softbank. -**************************** -Create a custom Ubuntu Image -**************************** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Create the custom Ubuntu Image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We will now create a custom Ubuntu image, which will use the base Softbank image and add our own customisations on top. The process is based off the NaoDevil's flasher. You can find the source code `here `_. @@ -88,17 +126,20 @@ Ensure you have Docker installed before continuing. This process will take a sig For subsequent runs, you will have the option to save time by reusing the base Ubuntu image. As long as you didn't make any changes to the root scripts (you are unlikely to as they are located inside of the NaoDevils code) you can continue with the saved base to save time. -****************** -Flashing the Robot -****************** - -You have 2 options to flash the robot: +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Flashing the Robot via USB +~~~~~~~~~~~~~~~~~~~~~~~~~~ +The main option to flash the robot is to create a flashable USB which is +recommended and likely to have the least complications. The second is to use +network flashing, which we have not used since `legacy`. +Look upstream at `NaoImage `_ (thank you NaoDevils!) +for `Network flash` and other fancy possibilities. -Create a Flashable USB (Recommended) -************************************ - -This approach is likely to work with the least amount of complications. +.. note:: + * The image by default should already have rUNSWift if you have compiled previously. You can check details about the flash by looking at ``image.commit.sha`` and ``image.build.time`` in the home dir. + * To sync a new version after flashing, follow the :ref:`syncing intructions above `. + * The default username and password for the robot after flashing is ``nao:nao``. Save yourself the hassle of typing this out repeatedly and add your key to ``image/home/nao/.ssh/authorized_keys`` and flash. Using the output opn file (``softwares/image.opn``), you can either use the official Nao Flasher or ``dd`` on Linux/Mac to flash the USB. @@ -127,43 +168,9 @@ Let go, and it should start flashing blue rapidly. The lights on the side of the .. tip:: If this step takes too long (>30 minutes) turn the robot off and retry flashing. -Look upstream at `NaoImage `_ (thank you NaoDevils!) for fancy possibilities like `Network flash`. - -********************************* -Robot Config, Name and Wifi Setup -********************************* -**If the robots are new** you will need to: - -* Add the robot to ``robots/robots.cfg`` - * You can find its head id via ``cat /sys/qi/head_id`` after ``ssh ``. - * Note you can flash safely without adding the robot to this file, and discover the head ID by ``ssh `` the robot calls out after flashing, and running the ``cat`` command. -* Create a copy of the default ``.cfg`` file called ``.cfg`` in ``image/home/nao/data/configs/`` -* Create a copy of the default ``.cfg`` file called ``.cfg`` in ``image/home/nao/data/configs/body/`` - -********************************* -Uploading rUNSWift -********************************* - -The image by default should already have rUNSWift. You can check details about the flash by looking at ``image.commit.sha`` and ``image.build.time`` in the home dir. - -To flash a new version, run: - -.. code-block:: bash - - make sync - -The robot should already be good to go with the IPs specified in `robots/robots.cfg` for LAN and wifi in SPL_A - -You can see the network settings in ``/etc/netplan`` directory. You can modify these files and then run ``sudo netplan apply`` to apply the changes. - -However, we do have scripts to manage these files as we detail further down below. Therefore, you shouldn't really need to modify them yourself. - -The default username and password for the robot after flashing is ``nao:nao``. -Save yourself the hassle of typing this out repeatedly and add your key to ``image/home/nao/.ssh/authorized_keys`` and flash. - -********************************* +~~~~~~~~~~~~~~~ Troubleshooting -********************************* +~~~~~~~~~~~~~~~ .. tip:: @@ -175,15 +182,27 @@ Troubleshooting ```` is likely ``nao.local`` for new or factory reset robots. This could be used instead of the IP address during setup. +********************************* +Robot Config, Name and Wifi Setup +********************************* +**If the robots are new** you will need to: + +* Add the robot to ``robots/robots.cfg`` + * You can find its head id via ``cat /sys/qi/head_id`` after ``ssh ``. + * Note you can flash safely without adding the robot to this file, and discover the head ID by ``ssh `` the robot calls out after flashing, and running the ``cat`` command. +* Create a copy of the default ``.cfg`` file called ``.cfg`` in ``image/home/nao/data/configs/`` +* Create a copy of the default ``.cfg`` file called ``.cfg`` in ``image/home/nao/data/configs/body/`` ********************************* Connecting to GameController Wifi ********************************* -To play a game by the SPL Rules, the ``runswift`` executable needs to send packets of +The robot should already be good to go with the IPs specified in `robots/robots.cfg` for LAN and wifi in SPL_A + +To play a game by the SPL Rules, the ``runswift`` code needs to send packets of information to, and respond to commands from, one specific soccer field's `GameController `_. Typically the competition organisers will provide the list of field SSIDs and any other details at the competition, for example ``SPL_A`` to ``SPL_E`` has been typical of RoboCup. -You can modify the WIFI network in ``/etc/netplan/wifi.yaml`` and then run ``sudo netplan apply``, or look at `make change-wifi`. +You can modify the WIFI network in ``/etc/netplan/wifi.yaml`` and then run ``sudo netplan apply``, or look at ``make change-wifi``. diff --git a/source/networking.rst b/source/getting_started/working_with_the_robot/networking.rst similarity index 100% rename from source/networking.rst rename to source/getting_started/working_with_the_robot/networking.rst diff --git a/source/getting_started/working_with_the_robot/running_runswift.rst b/source/getting_started/working_with_the_robot/running_runswift.rst new file mode 100644 index 0000000..f75d6c6 --- /dev/null +++ b/source/getting_started/working_with_the_robot/running_runswift.rst @@ -0,0 +1,120 @@ +################ +Running the code +################ + +You have two options, either run using systemd or run in an ssh terminal. +By default, all systemd services except foxglove will start on boot to be game ready. + +.. note:: + This is different to *legacy* TODO add link + +************* +Using systemd +************* + +#. Open an ssh connection to the robot by running + + .. code-block:: bash + + ssh nao@ + + .. tip:: + ``nao`` is the user name, and ```` is the hostname of the robot. + + .. note:: + For passwords, please :ref:`contact` us. + +#. **On the robot** (in the terminal with the ssh connection) + + To start a service + + .. code-block:: bash + + sudo systemctl start + + To stop a service + + .. code-block:: bash + + sudo systemctl stop + + .. note:: + The list of services are: + + - runswift_motion + - runswift_vision + - runswift_stateestimation + - runswift_comms + - runswift_behaviours + - runswift_hri + - runswift_startup + - runswift_errors + - foxglove + +#. Once the chest light is flashing green + **press the chest** or hold the 3 head sensors for one second to stiffen the robot + + +.. seealso:: + :ref:`button_presses` for ways to interact with the robot without a PC. + +~~~~~~~ +Example +~~~~~~~ + +Often we want to use foxglove to use various tools. This particular example is +the process we use for kinematics calibration. First ssh in, then use: + +.. code-block:: bash + + sudo systemctl stop runswift_behaviours + sudo systemctl start foxglove + +Then, you can connect to the robot using the foxglove web app at `http://:8765` + + +**************** +Using a terminal +**************** + +This method is useful for debugging since you can see the output of the code in the terminal. + +#. Open an ssh connection to the robot by running + + .. code-block:: bash + + ssh nao@ + + .. tip:: + ``nao`` is the user name, and ```` is the hostname of the robot. + + .. note:: + For passwords, please :ref:`contact` us. + +#. **On the robot** (in the terminal with the ssh connection) + + * Since systemd starts services by default, we need to stop them + + .. code-block:: bash + + sudo systemctl stop runswift_motion + sudo systemctl stop runswift_vision + sudo systemctl stop runswift_stateestimation + sudo systemctl stop runswift_comms + sudo systemctl stop runswift_behaviours + sudo systemctl stop runswift_hri + sudo systemctl stop runswift_startup + sudo systemctl stop runswift_errors + +~~~~~~~ +Example +~~~~~~~ + +First, run the code block above to kill all services. Then ssh in and run: + +.. code-block:: bash + + source robot_ws/install/setup.bash + ros2 launch motion_port motion_launch + +TODO check that's correct ^ \ No newline at end of file diff --git a/source/running/turning_on.rst b/source/getting_started/working_with_the_robot/turning_on.rst similarity index 100% rename from source/running/turning_on.rst rename to source/getting_started/working_with_the_robot/turning_on.rst diff --git a/source/images/2024_team_photo.JPG b/source/images/2024_team_photo.JPG new file mode 100644 index 0000000..f4f9640 Binary files /dev/null and b/source/images/2024_team_photo.JPG differ diff --git a/source/images/RCAP2024_team_photo.jpg b/source/images/RCAP2024_team_photo.jpg new file mode 100644 index 0000000..de02faf Binary files /dev/null and b/source/images/RCAP2024_team_photo.jpg differ diff --git a/source/index.rst b/source/index.rst index 4a0d547..0693fcc 100644 --- a/source/index.rst +++ b/source/index.rst @@ -6,30 +6,43 @@ Welcome to rUNSWift's Documentation! ==================================== -rUNSWift is a team from the University of New South Wales that competes in the `Standard Platform League `_ of RoboCup. +rUNSWift is a team from the University of New South Wales that competes in the +`Standard Platform League `_ of RoboCup. -.. image:: /images/2023_team_photo.JPG +.. note:: + In 2025, rUNSWift completely migrated to `ROS2 Humble `_. + If you wish to see the old documentation for the Ubuntu-based OS visit + https://runswift.readthedocs.io/en/2024/index.html. 2024 is referred to as + *legacy* in the docs. +.. image:: /images/2024_team_photo.JPG + +Contents +======== + +.. toctree:: + :maxdepth: 4 + :caption: Getting Started + + getting_started/work_in_progress + getting_started/setup_and_workspace/index + getting_started/working_with_the_robot/index + getting_started/tools/index .. toctree:: - :hidden: - :maxdepth: 1 - - setup/index - running/index - architecture - perception/index - motion/index - networking - 3d_simulation - tools/index - game_preparation/index - debugging/index - style_guide - contributing/index - working_remotely - past_research - code_releases_team_reports - team_photos - game_videos - contact + :maxdepth: 4 + :caption: Technical Documentation + + technical_documentation/architecture + technical_documentation/behaviour + technical_documentation/motion/index + technical_documentation/state_estimation/index + technical_documentation/vision/index + +.. toctree:: + :maxdepth: 3 + :caption: About + + about/publications/index + about/past_teams/index + about/contact diff --git a/source/perception/behaviour.rst b/source/perception/behaviour.rst deleted file mode 100644 index 7d1d2f8..0000000 --- a/source/perception/behaviour.rst +++ /dev/null @@ -1,22 +0,0 @@ -######### -Behaviour -######### - -In 2018, we modified our behaviour architecture to improve dynamic role switching. -From 2010, the higher level layers of rUNSWift’s behaviours have been written in Python, allowing faster development. Our behaviours are modelled off a -decision tree. Nodes are divided into two categories, roles and skills. Roles, such -as “Goalie” and “Penalty Striker”, define what the robot should be doing during -a game. Skills are specific actions a robot has chosen to take. - -Skills range from relatively high level actions, such as approaching the ball -or walking to a global point on the field, to lower level actions, such as stand or -crouch. This allows the low level skills to be inherited as components of several -higher level skills, which in turn are used by one or more roles. - -State transitions can happen a frequently when a robot is involved in ball -play. Under the old system, when transitions take place in high level skills, all -child skills must be reinitialised. This process creates a computational overhead -that reduced robot responsiveness, particularly during critical periods of play -around the ball. To mitigate this we redesigned our system so that all objects -are initialised at the start, and a reset routine is called on only the nodes of -interest when a transition takes place diff --git a/source/perception/index.rst b/source/perception/index.rst deleted file mode 100644 index a30a25b..0000000 --- a/source/perception/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -########## -Perception -########## - -.. toctree:: - :maxdepth: 2 - - vision/index - state_estimation/index - behaviour diff --git a/source/running/building.rst b/source/running/building.rst deleted file mode 100644 index ff97174..0000000 --- a/source/running/building.rst +++ /dev/null @@ -1,39 +0,0 @@ -######## -Building -######## - -To compile (build) the codebase for a V6 robot, run - -.. code-block:: bash - - $ build-relwithdebinfo-2.8.sh - -.. tip:: - - Optionally, you can also compile just a single program, such as - - .. code-block:: bash - - $ build-relwithdebinfo-2.1.sh offnao.bin - - Possible programs that can be built are listed below. - - ============================== ============================== ============================== - v6 v5 + offnao/vatnao native + offnao/vatnao - . . needed for v6 robot detector - ------------------------------ ------------------------------ ------------------------------ - build-relwithdebinfo-2.8.sh build-relwithdebinfo-2.1.sh build-relwithdebinfo-native.sh - ============================== ============================== ============================== - runswift runswift runswift - state-estimation-simulator.bin offnao.bin offnao.bin - . vatnao.bin vatnao.bin - . vatnao-legacy.bin vatnao-legacy.bin - . state-estimation-simulator.bin state-estimation-simulator.bin - ============================== ============================== ============================== - -.. note:: - By default, the maximum number of processors available will be used for compilation. - - -.. tip:: - Builds can fail in strange ways sometimes. Try ``build-relwithdebinfo-2.8.sh -B`` to do a clean build diff --git a/source/running/button_presses.rst b/source/running/button_presses.rst deleted file mode 100644 index e9e8553..0000000 --- a/source/running/button_presses.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _button_presses: - -############## -Button Presses -############## - -********************** -Chest Button Interface -********************** - -+------------------+-----------------+-------------------------------------------------------------------------------------------+ -| Button presses | Foot bumper | Action | -+==================+=================+===========================================================================================+ -| 1 | No | As per rules, set the robot to the penalised or unpenalised (playing) state | -+------------------+-----------------+-------------------------------------------------------------------------------------------+ -| 2 | No | Make body limp or stiff | -+------------------+-----------------+-------------------------------------------------------------------------------------------+ -| 2 | Yes | Make head limp or stiff | -+------------------+-----------------+-------------------------------------------------------------------------------------------+ -| 3 | No | Start or Stop runswift | -+------------------+-----------------+-------------------------------------------------------------------------------------------+ -| 3 | Yes | Restart (or at least stop) naoqi | -+------------------+-----------------+-------------------------------------------------------------------------------------------+ -| 4 | (Ignored) | Restart WiFi and ``changeField`` to the ``network.ssid`` in ``runswift.cfg`` | -+------------------+-----------------+-------------------------------------------------------------------------------------------+ -| hold | No | Shut down | -+------------------+-----------------+-------------------------------------------------------------------------------------------+ -| hold | Yes | Flash various boards, then reboot | -+------------------+-----------------+-------------------------------------------------------------------------------------------+ - -*********** -Head stroke -*********** - -``runswift`` can be started or killed by "stroking" the 3 head buttons -forwards or backwards, for details see `PR -#913 `__. - -.. warning:: - The Head stroke isn't working on the V6 yet. diff --git a/source/running/index.rst b/source/running/index.rst deleted file mode 100644 index 24d4a57..0000000 --- a/source/running/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -################# -Running the Robot -################# - -.. toctree:: - :maxdepth: 1 - - turning_on - building - syncing - running_runswift - button_presses - leds diff --git a/source/running/running_runswift.rst b/source/running/running_runswift.rst deleted file mode 100644 index c5ebe1e..0000000 --- a/source/running/running_runswift.rst +++ /dev/null @@ -1,76 +0,0 @@ -################ -Running runswift -################ - -#. Open an ssh connection to the robot by running - - .. code-block:: bash - - $ ssh nao@mario - - .. note:: - Replace mario with the name of the robot’s head you’re using - - .. tip:: - ``nao`` is the user name, and ``mario`` is the hostname of the robot. - - .. note:: - For passwords, please :ref:`contact` us. - -#. **On the robot** (in the terminal with the ssh connection), run - - .. code-block:: bash - - $ runswift - -#. Once the chest light is flashing green - **double press the chest** to stiffen the robot. - - -.. seealso:: - :ref:`button_presses` for ways to interact with the robot without a PC. - -******* -Options -******* - -Commonly used options are below: - -========================================= ======= ================================================================================== -Option Default Description -========================================= ======= ================================================================================== --T 18 Team Number (eg. 18) ------------------------------------------ ------- ---------------------------------------------------------------------------------- --n 2 Player Number (eg. 2) ------------------------------------------ ------- ---------------------------------------------------------------------------------- --s Game Name of top level body python behaviour skill to execute ------------------------------------------ ------- ---------------------------------------------------------------------------------- ---stateestimation.initial_pose_type GAME Type of initial pose (GAME/UNPENALISED/SPECIFIED) ------------------------------------------ ------- ---------------------------------------------------------------------------------- ---stateestimation.specified_initial_x 0 Initial x value in mm (if stateestimation.initial_pose_type == SPECIFIED) ------------------------------------------ ------- ---------------------------------------------------------------------------------- ---stateestimation.specified_initial_y 0 Initial y value in mm (if stateestimation.initial_pose_type == SPECIFIED) ------------------------------------------ ------- ---------------------------------------------------------------------------------- ---stateestimation.specified_initial_theta 0 Initial theta value in degrees (if stateestimation.initial_pose_type == SPECIFIED) -========================================= ======= ================================================================================== - -.. seealso:: - - ``runswift --help`` for complete list of options - -******* -Example -******* - -To run a robot with - -* FieldPlayer skill -* Starting from the centre of the field, facing opponent goal - -.. code-block:: bash - - $ runswift -s FieldPlayer --stateestimation.initial_pose_type SPECIFIED - - -.. tip:: - Modify the options in ``runswift.cfg`` to make it easier if you have a lot of options! diff --git a/source/running/syncing.rst b/source/running/syncing.rst deleted file mode 100644 index 3fac3de..0000000 --- a/source/running/syncing.rst +++ /dev/null @@ -1,44 +0,0 @@ -####### -Syncing -####### - -To sync code in the ``image/`` directory, such as behaviours and configs, run - -.. code-block:: bash - - $ nao_sync mario - -To sync the compiled ``runswift`` program, add the ``-r`` flag - -.. code-block:: bash - - $ nao_sync -r mario - -.. note:: - - Replace ``mario`` with the name of the robot's head you're using - - -******* -Options -******* - -Commonly used options are below. - -====== ========================================= -Option Description -====== ========================================= --r upload the compiled ``runswift`` program ------- ----------------------------------------- --d delete contents of ~/nao ------- ----------------------------------------- --g upload debugging symbols for gdb -====== ========================================= - -.. seealso:: - - ``nao_sync --help`` for complete list of options - -.. tip:: - - Options can be concatenated, such as ``nao_sync -rd mario``. diff --git a/source/setup/index.rst b/source/setup/index.rst deleted file mode 100644 index 5955910..0000000 --- a/source/setup/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -##### -Setup -##### - -.. toctree:: - :maxdepth: 2 - - pc_setup - nao_setup diff --git a/source/setup/pc_setup.rst b/source/setup/pc_setup.rst deleted file mode 100644 index 536a9ac..0000000 --- a/source/setup/pc_setup.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. _pc_setup: - -######## -PC Setup -######## - -.. warning:: - ⚠ ⚠ ⚠ This guide is probably so outdated it needs to be decommissioned. If you're here for rUNSWift Bootcamp, please follow - the instructions you have been provided in Discord, not anything on this page. - -.. note:: - If this is your first time using rUNSWift software, follow the instructions on this page. - For those that are looking to contribute to the codebase, please follow instructions on :ref:`pc-setup-contributing`. - -****************** -Install VirtualBox -****************** - -Download and Install `VirtualBox `_. - -************************ -Import rUNSWift VM Image -************************ - -#. Download OVA file from `http://robocup.web.cse.unsw.edu.au/runswift2/rUNSWift-VM.ova` -#. File -> Import Appliance -#. Select the Downloaded OVA file -#. Next -#. Import -#. Settings - #. System - * Motherboard - =========== ======= - Base Memory 4096 MB - =========== ======= - - .. tip:: - Memory size of 2GB is a minimum. - Recommendation is half your system memory. - * Processor - ============ ====== - Processor(s) 4 CPUs - ============ ====== - - .. tip:: - Maximum 1 CPU per 1.5GB Base Memory - Recommendation is equal to the number of cores on your system. Ignore the 'Invalid settings detected'. -#. Start - -.. tip:: - OVA file is very big (>5GB), and you have to be on campus or a CSE student to download it. - -.. tip:: - We have a smaller (3.2GB) OVA file for external users at `http://robocup.web.cse.unsw.edu.au/runswift2-htpasswd/rUNSWeenie.ova`. - -.. note:: - For passwords, please :ref:`contact` us. - - -.. _setup_network: - -****************************** -Setup Wireless/Wired Network -****************************** - -.. warning:: - You only have to follow these steps if you have to connect to an actual robot. - - -For a VM, it is necessary to bridge wireless networks and wired networks (when using LAN) -from the host machine to the VM. Follow these instructions in VirtualBox. - -#. Network - #. Adapter 2 - #. Enable Network Adapter - #. Attached to Bridged Adapter - #. Name should be your wired adapter - -.. note:: - In case you're unable to connect to a robot (i.e. ``ssh `` doesn't work), try installing `Wireshark `_ and monitoring the packets to diagnose the issue. Also try pinging by the expected IP address of the robot, ``ping .local``, and checking the output of ``avahi-browse -av``. diff --git a/source/technical_documentation/architecture.rst b/source/technical_documentation/architecture.rst new file mode 100644 index 0000000..2d639f2 --- /dev/null +++ b/source/technical_documentation/architecture.rst @@ -0,0 +1,94 @@ +############ +Architecture +############ + +The ``runswift`` infrastructure is fairly large, so this page lists some +key aspects and summaries. The best way to understand these in detail is +to read the reference papers and relevant code. + +ROS2 +---- + +We run ROS2 Humble on ubuntu based on the image provided by Nao Devils: +https://github.com/NaoDevils/NaoImage.git + +We have many packages within the codebase. Below is a quick summary of the main ones. + +=================== ========================================================================= +Package Description +=================== ========================================================================= +3rdparty Contains all 3rd party dependencies +behaviours Logic for the behaviours running on the robot +bringup Has higher level launch files for other packages +comms For communications from the robots to other robots and GameController +hri Human Robot Interaction; LEDs, buttons, touch sensors, speakers, etc. +kinematics Robot kinematics information +motion Robot movement +runswift_interfaces Interfaces for msgs between modules +stateestimation Robot localisation and ball tracking +vision Camera processing +=================== ========================================================================= + +Configuration +------------- + +We have many ways to configure the way things run on the robot, and we try to +follow the ROS2 pattern as closely as possible. + +Parameters +~~~~~~~~~~ + + +Launch files +~~~~~~~~~~~~ + +we have launch files. + +Configs +~~~~~~~ +The legacy way of using configs for each robot was to use .cfg files. We have +not yet got around to moving to proper ROS2 ways of doing this and instead read +in parameters from the config files as they were in legacy. The top level is +`runswift.cfg <../tree/master/image/home/nao/data/runswift.cfg>`__, with +per-robot configuration files in the +`robot.cfg <../tree/master/image/home/nao/data/configs>__`, or the robot body +config `robot.cfg <../tree/master/image/home/nao/data/configs/body>__`. Our +implementation was fairly inconsistent as we are probably going move to a more +ROS2 like way of doing things, so make sure to check the launch files for which +file takes precedence for each parameter. + + +Running Architecture +-------------------- + +By default, we want the code to be running on boot because we want it to be game +ready. To make sure this happens, follow the instructions HERE? (readme) + +Currently, we don't have any thread restarting logic as we were tight on time. +This is good for writing new code and debugging because you can see if it crashes +easily. However, if anyone reading this wants to implement it, read the 2024 +Threads section LINK LINK LINKs + + + +Logging +~~~~~~~ + +We have a cout-like interface for recording log messages to a file. For +example: + +``llog(INFO) << "RUNSWIFT soccer library spinning up!" << endl;`` + +Log files are saved in /var/volatile/runswift on the robot, and there is +one log file per source directory. The log levels available are SILENT, +QUIET, FATAL, ERROR, WARNING, INFO, VERBOSE, DEBUG1, DEBUG2, and DEBUG3. +Setting a log level will record messages of that level or higher. The +default log level is SILENT, and can be overridden using one of the +options mechanisms listed in the options section. e.g. "-l INFO" will +record messages at level SILENT, QUIET, FATAL, ERROR, WARNING, or INFO. +Using llog (especially in tight loops) takes resources, even if the set +log level is higher (e.g. "-l SILENT") than the one passed to llog (e.g. +"llog(DEBUG3)"). + + + diff --git a/source/architecture.rst b/source/technical_documentation/behaviour.rst similarity index 52% rename from source/architecture.rst rename to source/technical_documentation/behaviour.rst index c4fbfeb..a26be24 100644 --- a/source/architecture.rst +++ b/source/technical_documentation/behaviour.rst @@ -1,86 +1,27 @@ -############ -Architecture -############ - -The ``runswift`` infrastructure is fairly large, so this page lists some -key aspects and summaries. The best way to understand these in detail is -to read the reference papers and relevant code. - -Overview - libraries, libagent, runswift and offnao ---------------------------------------------------- - -``libagent`` is a library loaded into ``naoqi`` and how ``runswift`` -communicates with the robot hardware on Nao v5 and earlier (OS 2.1 and -earlier). - -``soccer`` & ``soccer-static`` are the basic toolchain-independent -modules (perception without cameras, etc.). The static version is -for ``robot-static``, and the dynamic version is for [[offnao]]. - -``robot-static`` is ``soccer-static`` with hardware-specific modules -(camera, some parts of motion). - -``runswift`` is ``robot-static`` with ``main()``. - -[[offnao]] is our current C++/Qt visual debugger that connects to -``runswift`` via TCP port 10125. It can also save and load recordings in a few -different formats - -If you poke around the cmake files, they should correlate with what's -said here, but if it doesn't, the cmake files take precedence (and -please update this). - -Drivers and libagent --------------------- - -Not sure about drivers? Naoqi modules like ``libagent`` are loaded `in -image/etc/naoqi/autoload.ini <../tree/master/image/etc/naoqi/autoload.ini>`__ - -If you poke around the files, they should correlate with what's -said here, but if it doesn't, the files take precedence (and -please update this). - -Nao v5, OS 2.1, and earlier -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``libagent`` is our communications bridge to the robot. It is a library -that we wrote within Aldebaran's proprietary NaoQi SDK that receives -information such as joint angles, and sends information such as LED -commands. It is also responsible for `button -presses `__. libagent communicates with -our executable (runswift) via a shared memory object. (linux allows you -to allocate named memory that is shared with other processes.) - -Nao v6, OS 2.8, and later -~~~~~~~~~~~~~~~~~~~~~~~~~ - -LoLA is Aldebaran's communications bridge to Aldebaran's proprietary NaoQi SDK. ``lola`` is a process separate to ``naoqi``. Access is only available on special RoboCup versions of the OS. To enable access, you need to have ``/home/nao/robocup.conf`` on the Nao. This file can be empty. ``lola`` will then create a socket file ``/tmp/robocup`` which supports msgpack for read and write. See ``robot/motion/LoLAData.cpp`` for more details. - -rUNSWift --------- - -options -~~~~~~~ - -There are many options to the runswift executable. They can be put on -the command line, in the configuration file -`runswift.cfg <../tree/master/image/home/nao/data/runswift.cfg>`__, in -the per-robot configuration file , or sent from off-nao. They are -configured in options.cpp, and viewable by running "runswift --help". - -Call tree -~~~~~~~~~ - -At the top of our call tree is main, naturally. -`main.cpp <../tree/master/robot/main.cpp>`__ launches threads for most -of our top level-modules, such as Perception and Motion. The threads -continuously run in a loop, independent of each other. Perception is -[currently] the only top-level module that contains other top-level -modules, namely Kinematics, Vision, Localisation, and Behaviour, which -are executed in that order. Behaviour contains a bridge to python, and -calls the execute method of a top-level python skill -(`GameController.py <../tree/master/image/home/nao/data/behaviours/skills/GameController.py>`__ -skill by default). +######### +Behaviour +######### + +In 2018, we modified our behaviour architecture to improve dynamic role switching. +From 2010, the higher level layers of rUNSWift’s behaviours have been written in Python, allowing faster development. Our behaviours are modelled off a +decision tree. Nodes are divided into two categories, roles and skills. Roles, such +as “Goalie” and “Penalty Striker”, define what the robot should be doing during +a game. Skills are specific actions a robot has chosen to take. + +Skills range from relatively high level actions, such as approaching the ball +or walking to a global point on the field, to lower level actions, such as stand or +crouch. This allows the low level skills to be inherited as components of several +higher level skills, which in turn are used by one or more roles. + +State transitions can happen a frequently when a robot is involved in ball +play. Under the old system, when transitions take place in high level skills, all +child skills must be reinitialised. This process creates a computational overhead +that reduced robot responsiveness, particularly during critical periods of play +around the ball. To mitigate this we redesigned our system so that all objects +are initialised at the start, and a reset routine is called on only the nodes of +interest when a transition takes place + +# Reilly note: Adding from architecture in case any blackboard stuff is relevant. Threads ~~~~~~~ @@ -126,35 +67,9 @@ blackboard should not contain pointers. Adding a variable to the blackboard does not make it immediately accessible in offnao. You have to manually archive it, see [[Blackboard Serialization]]. -Logging -~~~~~~~ -We have a cout-like interface for recording log messages to a file. For -example: - -``llog(INFO) << "RUNSWIFT soccer library spinning up!" << endl;`` - -Log files are saved in /var/volatile/runswift on the robot, and there is -one log file per source directory. The log levels available are SILENT, -QUIET, FATAL, ERROR, WARNING, INFO, VERBOSE, DEBUG1, DEBUG2, and DEBUG3. -Setting a log level will record messages of that level or higher. The -default log level is SILENT, and can be overridden using one of the -options mechanisms listed in the options section. e.g. "-l INFO" will -record messages at level SILENT, QUIET, FATAL, ERROR, WARNING, or INFO. -Using llog (especially in tight loops) takes resources, even if the set -log level is higher (e.g. "-l SILENT") than the one passed to llog (e.g. -"llog(DEBUG3)"). - -Adapters -~~~~~~~~ - -Including the blackboard in every file that needs to access a blackboard -variable has led to some unreasonably long compiles in previous years. -To alleviate this, we are using an Adapter-like pattern, where only the -files representing the top-level modules access the variables on the -blackboard. Blackboard.hpp should only be included from these special -Adapter.cpp files, and the blackboard should only friend these -Adapters. +# Reilly note, same as above + Python Infrastructure --------------------- @@ -225,4 +140,4 @@ Key directories relating to the python interface: BehaviourRequest instance. Whatever else happens is up to your python architecture and can be customised to match some form of state machine / decision tree / other behaviour system implemented in - python. + python. \ No newline at end of file diff --git a/source/motion/index.rst b/source/technical_documentation/motion/index.rst similarity index 81% rename from source/motion/index.rst rename to source/technical_documentation/motion/index.rst index 7b43529..cce14ee 100644 --- a/source/motion/index.rst +++ b/source/technical_documentation/motion/index.rst @@ -6,18 +6,13 @@ Motion Overview ******** -The motion module is run in its own thread with the highest priority on the robot, +The motion module should be run in its own thread with the highest priority on the robot, as joint angles need to be calculated at approximately 82 frames per second to maintain stability. -The MotionAdapter class controls this thread and is the gateway for communicating in -and out of the motion module. Within motion, there are 3 main areas. - -============= ================================================================== -**Touch** receives input from Lola, eg gyroscopes, accelerometers, etc -------------- ------------------------------------------------------------------ -**Generator** generates joint values from the behaviour request and sensor input -------------- ------------------------------------------------------------------ -**Effector** outputs joint values to Lola -============= ================================================================== +We haven't quite figured out if that's happening yet in ROS2. +The MotionAdapter node controls the motion and handles the motion processing. In +legacy, there were 3 areas, but now touch and effector are handled but the nao_lola package. +Now, it essentially takes in a MotionCommand, wraps it with SafetySkill (for handling ref +pickups and getups when falling), and runs it through the generators. ********** Literature @@ -58,6 +53,9 @@ Other reports that include motion concepts to varying degrees: Actions ******* +.. note:: + These are not ROS2 actions, these are physical actions performed by the robot + Most of the work in producing actions happens in the generator area. The main generator class is the DistributedGenerator that calls upon subsequent generators depending on the requested action. There are also @@ -65,12 +63,11 @@ some basic generators that all generated joints get passed through, such as the ClippedGenerator, which ensures that joint requests do not go past their maximum values. -All actions are defined in -``$RUNSWIFT_CHECKOUT_DIR/robot/types/ActionCommand.hpp``. If you do add +All actions are defined in MotionCommand [TODO link?]. If you do add a new ActionType to it, remember to fill out all the corresponding -enums, such as the action's priority. These priorities define what -actions can be interrupted, for example the get up action has the -highest priority. +maps in DistributedGenerator, if it needs a special priority or head movement. +These priorities define what actions can be interrupted, for example the get up +action has the highest priority. To set a generator for a particular body action, you'll need to add something like this to DistributedGenerator: @@ -79,7 +76,7 @@ something like this to DistributedGenerator: bodyGenerators[Body::BACK_FLIP] = (Generator*)(new BackFlipGenerator()); if (!bodyGenerators[Body::BACK_FLIP]) - llog(FATAL) << "bodyGenerators[BACK_FLIP] is NULL!" << std::endl; + RCLCPP_FATAL(motion_node_->get_logger(), "bodyGenerators[BACK_FLIP] is NULL!"); All generators should subclass the basic Generator.hpp class and fill in the virtual functions, such as isActive, reset, and stop. Along with the @@ -119,45 +116,6 @@ Dynamic actions are for more complicated movements, such as the walk and kicks. Instead of reading the joint values from a pos file, they are set in the relevant generator's ``makeJoints`` function. -Actions + Python ----------------- - -To add a new action into the Python code, you'll need to add to the -python wrapping of ActionCommand in -``$RUNSWIFT_CHECKOUT_DIR/robot/perception/behaviour/python/wrappers/ActionCommand_wrap.cpp``. - -Then add it to -``$RUNSWIFT_CHECKOUT_DIR/image/home/nao/data/behaviours/actioncommand.py``. -For example here is the one for ``goalieDiveLeft``: - -.. code:: python - - def goalieDiveLeft(): - return _type_only_body_command(robot.ActionType.GOALIE_DIVE_LEFT) - - -You will then be able to call your new action from a Python behaviour -like so: - -.. code:: python - - self.world.b_request.actions.body = actioncommand.goalieDiveLeft() - -The motion module will know which behaviour is running as -MotionAdapter.cpp will read it from the blackboard, and then call upon -the appropriate generator. - -.. code:: c - - // Get the motion request from behaviours - int behaviourReadBuf = readFrom(behaviour, readBuf); - ActionCommand::All request = readFrom(behaviour, request[behaviourReadBuf]).actions; - ... - ... - ... - // Get the joints requested by whichever generator we're using - JointValues joints = generator->makeJoints(&request, &odometry, sensors, bodyModel, ball.x(), ball.y(), motionDebugInfo); - ********** Kinematics ********** diff --git a/source/perception/state_estimation/ego_ball_tracker.rst b/source/technical_documentation/state_estimation/ego_ball_tracker.rst similarity index 100% rename from source/perception/state_estimation/ego_ball_tracker.rst rename to source/technical_documentation/state_estimation/ego_ball_tracker.rst diff --git a/source/perception/state_estimation/index.rst b/source/technical_documentation/state_estimation/index.rst similarity index 100% rename from source/perception/state_estimation/index.rst rename to source/technical_documentation/state_estimation/index.rst diff --git a/source/perception/state_estimation/localiser.rst b/source/technical_documentation/state_estimation/localiser.rst similarity index 100% rename from source/perception/state_estimation/localiser.rst rename to source/technical_documentation/state_estimation/localiser.rst diff --git a/source/perception/state_estimation/robot_filter.rst b/source/technical_documentation/state_estimation/robot_filter.rst similarity index 100% rename from source/perception/state_estimation/robot_filter.rst rename to source/technical_documentation/state_estimation/robot_filter.rst diff --git a/source/perception/state_estimation/team_ball_tracker.rst b/source/technical_documentation/state_estimation/team_ball_tracker.rst similarity index 100% rename from source/perception/state_estimation/team_ball_tracker.rst rename to source/technical_documentation/state_estimation/team_ball_tracker.rst diff --git a/source/perception/vision/adaptive_thresholding.rst b/source/technical_documentation/vision/adaptive_thresholding.rst similarity index 100% rename from source/perception/vision/adaptive_thresholding.rst rename to source/technical_documentation/vision/adaptive_thresholding.rst diff --git a/source/perception/vision/ball_detector.rst b/source/technical_documentation/vision/ball_detector.rst similarity index 100% rename from source/perception/vision/ball_detector.rst rename to source/technical_documentation/vision/ball_detector.rst diff --git a/source/perception/vision/connected_component_analysis.rst b/source/technical_documentation/vision/connected_component_analysis.rst similarity index 100% rename from source/perception/vision/connected_component_analysis.rst rename to source/technical_documentation/vision/connected_component_analysis.rst diff --git a/source/perception/vision/field_feature_detector.rst b/source/technical_documentation/vision/field_feature_detector.rst similarity index 100% rename from source/perception/vision/field_feature_detector.rst rename to source/technical_documentation/vision/field_feature_detector.rst diff --git a/source/perception/vision/index.rst b/source/technical_documentation/vision/index.rst similarity index 93% rename from source/perception/vision/index.rst rename to source/technical_documentation/vision/index.rst index 9e8b489..9c19b45 100644 --- a/source/perception/vision/index.rst +++ b/source/technical_documentation/vision/index.rst @@ -7,7 +7,6 @@ The basic structure of the vision system is as follows. .. image:: /draw.io/vision.png .. toctree:: - :maxdepth: 2 adaptive_thresholding connected_component_analysis diff --git a/source/perception/vision/robot_detector.rst b/source/technical_documentation/vision/robot_detector.rst similarity index 100% rename from source/perception/vision/robot_detector.rst rename to source/technical_documentation/vision/robot_detector.rst diff --git a/source/tools/index.rst b/source/tools/index.rst deleted file mode 100644 index c1451d5..0000000 --- a/source/tools/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -##### -Tools -##### - -.. toctree:: - :maxdepth: 2 - - offnao/index - vatnao - vatnao_legacy diff --git a/source/tools/offnao/index.rst b/source/tools/offnao/index.rst deleted file mode 100644 index edfdecf..0000000 --- a/source/tools/offnao/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -###### -Offnao -###### - -Offnao is a tool built in house that collects, saves, restores and streams data -from Nao robots. It can record all the data from the robot’s sensors, including -either the colour classified or raw camera data. If given the raw camera data -Offnao can also run the vision system offline. Offnao also collects information -about the internal state of the robot, such as its beliefs about its position, team -mate position and ball position, along with what the vision system has detected. - -All this information can be displayed through various visualisation methods, -including annotated versions of the robot’s camera image and an overhead field -view. - -.. figure:: /images/offnao.png - -Kinematic offsets can be calibrated to compensate for differences in the head mounting -and looseness in the robot’s joints. Debug logs recorded by the main code may -be viewed. Finally, raw data from the non vision sensors, such as sonar and foot -sensors, can be monitored. - -.. toctree:: - :maxdepth: 2 - - overview diff --git a/source/tools/offnao/overview.rst b/source/tools/offnao/overview.rst deleted file mode 100644 index 0537997..0000000 --- a/source/tools/offnao/overview.rst +++ /dev/null @@ -1,221 +0,0 @@ -######## -Overview -######## - -.. figure:: /draw.io/overview_tab.png - - -#. :ref:`field_view` -#. Top Image -#. Bottom Image -#. Blackboard Variables - -.. _field_view: - -********** -Field View -********** - -Field View shows many things that our robot knows about the world and shows behaviour intentions. - -.. _robot_pose: - -Robot Pose -########## - -Robot Pose and Covariance is displayed using a pacman-like symbol. - -.. figure:: /images/pose.png - -**θ** indicates one standard deviation of the robot's heading both in clockwise and anticlockwise direction. - -The covariance ellipse indicates how accurately the position of the robot is known. -If a covariance ellipse is close to a circle, the robot is unaware of its position equally in all directions, but if -the covariance ellipse is stretched along one of it's axes, the robot knows its position well along the short axis, but not along the long axis. - -.. tip:: - If the pacman's mouth is wide open, it is highly unsure of its heading. - -.. tip:: - Covariance ellipses are used commonly in robot kalman filters, so search google to learn more. - -My Pose -******* - -My pose is the pose hypothesis used in behaviours, and can be identified by a :ref:`robot_pose` symbol with a **white ellipse**. - -.. figure:: /images/my_pose.png - -My Pose Hypotheses -****************** - -All the robot pose hypotheses are **yellow**, and use the :ref:`robot_pose` symbol. -The **brush thickness** of the covariance ellipse is the **weight of hypothesis**. - -.. figure:: /images/hypotheses.png - -The left and right hypotheses in the image have 1.0 and 0.03 weight respectively. -The right hypotheses has an extremely small brush thickness that ends up almost invisible. - - -.. _teammate_pose: - -Teammate Pose -************* - -Teammate's pose is shown in its corresponding :ref:`color`, and uses the :ref:`robot_pose` symbol. - -.. _ball: - -Ball Position and Velocity -########################## - -======= =========================== -Element Description -======= =========================== -Dot Ball Position -------- --------------------------- -Ellipse Position Covariance Ellipse -------- --------------------------- -Line Ball Velocity -======= =========================== - -The direction of the line from the ball, is the direction it is moving. - -.. tip:: - - The length of the line is how far the ball would travel over **one second** if the ball travelled at constant - velocity. - -EgoBall -******* - -EgoBall is shown in **yellow**, and use the :ref:`ball` symbol. - -.. figure:: /images/egoball.png - -TeamBall -******** - -TeamBall is shown in **black**, and use the :ref:`ball` symbol as below, - -.. figure:: /images/teamball.png - -Teammate's Ball -*************** - -A teammate's ball is shown in its corresponding :ref:`color`, and uses the :ref:`ball` symbol. - -.. _color: - -Color -##### - -A teammate's color is - -* **red** if **playing** the ball -* **blue** if **assisting** -* otherwise, depends on it's :ref:`positioning` - -.. _positioning: - -Positioning -########### - -Positionings are defined in ``robot/utils/PositioningDefs.hpp``. - -================================================ ======= ====== -Positioning Color Letter -================================================ ======= ====== -POSITIONING_NONE black NA -POSITIONING_AGAINST_KICKING_TEAM_SUPPORTER magenta F -POSITIONING_AGAINST_KICKING_TEAM_DEFENDER black D -POSITIONING_AGAINST_KICKING_TEAM_UPFIELDER cyan U -POSITIONING_FIND_BALL_FINDER gray FB -POSITIONING_AGAINST_DRIBBLE_TEAM_RIGHT_SUPPORTER white RS -POSITIONING_AGAINST_DRIBBLE_TEAM_SHOOTER cyan SH -POSITIONING_AGAINST_DRIBBLE_TEAM_LEFT_SUPPORTER magenta LS -POSITIONING_AGAINST_DRIBBLE_TEAM_SWEEPER black SW -================================================ ======= ====== - -Positioning Letter -################## - -The letter above a :ref:`teammate_pose` indicates it's positioning, as listed in :ref:`positioning`. - -Player Number -############# - -The number below a :ref:`teammate_pose` indicates it's player number. - -Teammate WalkingTo -################## - -The position of where a teammate robot is moving to when anticipating or in global find ball -is shown with a **50% opacity** :ref:`teammate_pose` symbol. - - -Robot Observations -################## - -Visual robot observations are shown using a **green** :ref:`robot_pose` symbol. - -.. figure:: /images/obstacle.png - -Observed Balls -############## - -Balls directly from the vision module are shown as an **orange dot**, as below - -.. figure:: /images/ball_obs.png - -Observed Field Features -####################### - -Observed T-Junctions and corners are displayed using **black**, as below - -.. figure:: /images/ff_obs.png - -Observed centre-circle is displayed with **orange** if the orientation is known or **red** otherwise. - -.. figure:: /images/cc_obs.png - -Observed field lines are displayed in **red**. - -Ball Manoeuvre -############## - -A robot's ball manouevre intention is displayed using a colored sector extending -from the ball's current location to the target ball location (indicated with a **pink** dot) - -**Green** cone indicates a **kick**, while **blue** indicates a **dribble** intention. - -The centre angle of the sector indicates the heading accuracy that must be achieved for the robot to execute the manoeuvre when lining up with the ball. - -The radius of the sector may be finite or infinite. A finite radius indicates that the robot will try and control its kick strength to aim for a certain field coordinate, -while an infinite radius indicates that the robot will try and kick the ball in the direction of the sector with maximum power. - -A maximum power kick towards the opponent goal: - -.. figure:: /images/ball_manouevre.png - -A dribble towards the opponent goal box: - -.. figure:: /images/ball_manouevre_dribble.png - -A controlled power kick towards the opponent goal box: - -.. figure:: /images/ball_manouevre_soft.png - -.. note:: - Dribble strength is **not** controllable - -Anticipate Position -################### - -The intended anticipate position of a robot that is executing an Anticipate or TeamFindBall skill is visualised using a grey -:ref:`robot_pose`, as below. The heading variance of the pie-shape indicates the acceptable heading error once the robot is at its -anticipate position. - -.. figure:: /images/anticipate_position.png - diff --git a/source/tools/vatnao.rst b/source/tools/vatnao.rst deleted file mode 100644 index a0d9d80..0000000 --- a/source/tools/vatnao.rst +++ /dev/null @@ -1,202 +0,0 @@ -###### -Vatnao -###### - -As part of our 2016-17 Vision System changes we developed a tool to assist in -development and debugging. The tool, Vatnao, runs the vision system on a local -machine using logs recorded on the robot. It allows the developer to examine -variables, annotate images based on how Vision processes the raw frames, and -even adjust configuration in real time. We used it heavily as part of development -of the ball detector to speed up the development cycle, reducing testing time, -quickly identifying problem cases and allowing us to quickly evaluate the effects -of tweaks and changes to our code base. - -Vatnao has also allowed us to break down the components of each detector. -For example, in the case of the ball detector, each heuristic can be broken down -and displayed separately to determine optimal values for the checks. The tool -also handles other modules of vision, such as field feature and robot detection. - -For basic usage build rUNSWift, then run: - -.. code-block:: bash - - vatnao -f some/offnao/dump/with/raw/images.ofn - -Vision Debug Module (VDM) -========================= - -Perhaps the most useful tool in vatnao, is the ability to view and "annotate" the regions as they are being processed. -This has been used in the past by sections like ball detector, to see how the ball regions are being broken down. The process is relatively simple. - -A word of warning, only one section of code can have access to the vision debug module at a time. It's polite to wrap any of your debugging in `#ifdef` catches and remove the `#define` before merging -your code into master. Use a name unique to your work, for example, if you were working on the `Foo` module: - -.. code-block:: c++ - - // ... - - #define FOO_USES_VDM - - // ... - - #ifdef FOO_USES_VDM - vdm->addOption("Foo's checkbox"); - #endif - -Importing the vdm ------------------ - -The vision debug module is handled by a single global pointer, `vdm`, defined in `soccer.hpp`. Whenever running vatnao, `vdm` will be initialised, otherwsie will be left as `NULL`. -To import, add the following to the head of any code you are debugging. - -.. code-block:: c++ - - #ifdef FOO_USES_VDM - - #include "VisionDebuggerInterface.hpp" - #include "soccer.hpp" - - #endif - -Setting vdm options -------------------- - -It's possible to set options that you can toggle in the vatnao user interface, to help fine tune what you want to show or adjust parameters. For example, ball detector used options to decide whether or not to overlay the region with what it thought were the black spots. Or, if you're not sure what's the best value for some parameter, just set it to the value of an option and change it at runtime to see how it changes the outcome. - -There are three types of options: - -Checkboxes, defined with: - -.. code-block:: c++ - - vdm->addOption("Single argument for checkboxes"); - -Dropdowns, defined with: - -.. code-block:: c++ - - vector aList; - aList.push_back("of"); - aList.push_back("all"); - aList.push_back("the"); - aList.push_back("options"); - vdm->addOption("The option name and", aList); - -Numeric, defined with: - - -.. code-block:: c++ - - vdm->addNumericOption("Single argument for numeric"); - -The default value for checkboxes is `false`, the default value for dropdowns is whatever you insert first, the default value for numeric is `0`. -Each option must only be set once, and cannot be removed during runtime. It's best to put them in the constructor for a class you're trying to debug. For example: - -.. code-block:: c++ - - #ifdef FOO_USES_VDM - - if (vdm != NULL) { - vdm->addOption("Show Outline"); - } - - #endif - -Using vdm options ------------------ - -To use vdm options in the codebase, use the `vdm->getQuery()` method. This returns a `VisionDebugQuery` which has a map of the option values and another map of numeric values. - -.. code-block:: c++ - - #ifdef FOO_USES_VDM - - if (vdm != NULL) { - VisionDebugQuery q = vdm->getQuery(); - if (q.options["Show Outline"] == "true") { - /* ... */ - } - threshold_value_ = q.numeric_options["Threshold"]; - } - - #endif - -> Important Note: The value returned by checkboxes is actually a string. Either `"true"` or `"false"`. It cannot be treated as a normal boolean unless you convert it. - -> Another Note: The value of a numeric option is a double. If you intend to use it as an integer it must be cast. - -Using vdm message ------------------ - -There is a space in vatnao for displaying some message, this can be set in one of two ways. First: - -.. code-block:: c++ - - #ifdef FOO_USES_VDM - - if (vdm != NULL) { - vdm->setDebugMessage("Directly through message"); - // OR - vdm->msg << "Using streaming " << "like std::cout" << std::endl; - vdm->msg << "Which can continue in multiple places" << std::endl; - vdm->msg << "And easily be used with " << variables << std::endl; - vdm->msg << "To confirm, just call setDebugMessage without arguments"; - - vdm->setDebugMessage(); - } - - #endif - -Calling `setDebugMessage` overrides whatever was previously written and clears the `vdm->msg` buffer. - -Using the VisionPainter ------------------------ - -It is possible to annotate directly onto a given region, right from your codebase. This was used, for example, in ball detector to show what the ball detector was seeing whenever it looked at a given region. -As the developer, you are given two indexes in the `VisionDebugQuery`: `q.region_index` and `q.subregion_index`, set through the vatnao interface. -Since you define the regions, they don't have any meaning, but are simply helpers to make it easy to navigate from the interface. But a good standard to use is to treat the `q.region_index` as the index of the region in the `regions`/`roi` array, and the `q.subregion_index` as any variation on that region that your code might produce. -The indexes are unbounded unsigned integers, so they will need to be checked. - -The `VisionPainter` itself is a simple interface that allows you to draw on regions you pass in through the `vdm->getGivenRegionOberlayPainter()` method. -In the example below, VisionPainter would draw a red circle of radius `5` at coordinate `10`, `10` in the region specified by the `q.region_index`, as long as the `Draw Circle` checkbox has been checked. - -.. code-block:: c++ - - #ifdef FOO_USES_VDM - - if (vdm != NULL) { - VisionDebugQuery q = vdm->getQuery(); - if (q.region_index < info_middle_.roi.size()) { - VisionPainter *p = vdm->getGivenRegionOverlayPainter(info_middle_.roi[q.region_index]); - if (q.options["Draw Circle"] == "true") { - p->drawCircle(10, 10, 5, VisionPainter::RED); - } - } - } - - #endif - -The `VisionPainter` has the following methods: - -* 'draw(x, y, colour)' or 'draw(x, y, r, g, b)' - - Fills the pixel at the given x, y coordinates with the given colour. - -* 'drawLine(x1, y1, x2, y2, colour)' or 'drawLine(x1, y1, x2, y2, r, g, b)' - - Draws a line between the two given points of the given colour. - -* 'drawRect(x, y, w, h, colour)' or 'drawRect(x, y, w, h, r, g, b)' - - Draws a rectangle starting at the given x, y coordinates, of the given width and height, in the given colour. - -* 'drawCircle(x, y, radius, colour)' or 'drawCircle(x, y, radius, r, g, b)' - - Draws a circle at the given x, y coordiantes with the given radius, in the given colour. - - -Defined Colours are RED, GREEN, BLUE, YELLOW, ORANGE, PURPLE, PINK, CYAN, LIME, WHITE, BLACK and GREY. - -Whatever region you pass in will be shown twice in vatnao, plain, and with annotations. - -Check out `robot/perception/vision/VisionDebuggerInterface.hpp` for all methods you can call. diff --git a/source/tools/vatnao_legacy.rst b/source/tools/vatnao_legacy.rst deleted file mode 100644 index 6863cab..0000000 --- a/source/tools/vatnao_legacy.rst +++ /dev/null @@ -1,6 +0,0 @@ -############# -Vatnao Legacy -############# - -Vatnao legacy is an old version of vatnao, which is still -being used for debugging the ball detector.