diff --git a/README.md b/README.md index eb6eed7c4..a8947b9f3 100644 --- a/README.md +++ b/README.md @@ -15,14 +15,7 @@ All code is written as individual ROS 2 packages. The workspace is managed using the [pixi](https://pixi.sh) package manager. This allows us to have reproducible builds and easy user space dependency management similar to tools like `uv` or `cargo`. This also means that no system wide ROS installation or superuser privileges are required to install or run the code. -Full step-by-step instructions for installing the Bit-Bots software stack and ROS 2 can be found in our documentation [here](https://doku.bit-bots.de/meta/manual/tutorials/install_software_ros2.html). - - -Run the following command inside this repository to build the workspace. All dependencies will be installed automatically. Make sure you have [pixi](https://pixi.sh) installed. A few optional proprietary dependencies will be needed for full functionality, see the documentation for details. - -``` shell -pixi run build -``` +Follow our [installation guide](https://docs.bit-bots.de/meta/manual/tutorials/installation.html) for a quick installation or step-by-step instructions. ## Using the workspace @@ -38,7 +31,13 @@ alternatively, you can run individual commands inside the workspace without acti pixi run ``` -To see some predefined / commands, run +To build the workspace, run the following command in the terminal: + +``` shell +pixi run build +``` + +To see some predefined tasks / commands, run ``` shell pixi task list @@ -49,7 +48,7 @@ pixi task list To deploy the software to a robot, run ``` shell -pixi run deploy +pixi run deploy ``` For more information on the deployment tooling, see [this documentation](scripts/README.md). diff --git a/scripts/README.md b/scripts/README.md index 0bffb1762..30dc4c414 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -8,12 +8,12 @@ This tool is also callable via `pixi run deploy `. Deploy, configure, and launch the Bit-Bots software remotely on a robot. This tool can target all, multiple, or single robots at once, specified by their hostname, robot name, or IP address. -Five different tasks can be performed: +These different tasks can be performed: 1. Synchronize the local source code to the target workspace -3. Configure game-settings and wifi on the target -4. Build (compile) the workspace on the target -5. Launch the teamplayer software on the target +2. Configure game-settings and wifi on the target +3. Build (compile) the workspace on the target +4. Launch the teamplayer software on the target ### Example usage diff --git a/scripts/deploy/deploy_robots.py b/scripts/deploy/deploy_robots.py index 54e9c0481..ff5282782 100644 --- a/scripts/deploy/deploy_robots.py +++ b/scripts/deploy/deploy_robots.py @@ -118,8 +118,8 @@ def _parse_arguments(self) -> argparse.Namespace: parser.add_argument( "-w", "--workspace", - default=".", - help="Path to the workspace directory to deploy to. Defaults to the current directory.", + default="/home/bitbots/bitbots_main", + help="Path to the workspace directory to deploy to. Defaults to '/home/bitbots/bitbots_main'.", ) parser.add_argument("--skip-local-repo-check", action="store_true", help="Skip the local repository check.") diff --git a/scripts/make_basler.sh b/scripts/make_basler.sh index e3ad8a01f..74033db94 100755 --- a/scripts/make_basler.sh +++ b/scripts/make_basler.sh @@ -7,6 +7,7 @@ set -eEo pipefail # Go to the download button and copy the link address. PYLON_DOWNLOAD_URL="https://data.bit-bots.de/pylon_7_4_0_14900_linux_x86_64_debs.tar.gz.gpg" PYLON_VERSION="7.4.0" +REQUIRED_UBUNTU_VERSION="24.04" # Check let the user confirm that they read the license agreement on the basler website and agree with it. echo "You need to confirm that you read the license agreements for pylon $PYLON_VERSION on the basler download page (https://www.baslerweb.com/en/downloads/software-downloads/) and agree with it." @@ -26,6 +27,20 @@ else SHOW_PROGRESS="--show-progress" fi +check_os_is_required_ubuntu_version () { + # Check if the OS is ubuntu + if [[ "$(lsb_release -is)" != "Ubuntu" ]]; then + echo "This driver package only supports Ubuntu. Please install Ubuntu $REQUIRED_UBUNTU_VERSION and try again." + exit 1 + fi + + # Check if the ubuntu version is the required one + if [[ "$(lsb_release -rs)" != "$REQUIRED_UBUNTU_VERSION" ]]; then + echo "This driver package only supports Ubuntu $REQUIRED_UBUNTU_VERSION. Please install Ubuntu $REQUIRED_UBUNTU_VERSION and try again." + exit 1 + fi +} + check_internet_connection () { # Check if we have an internet connection, except in the ci as azure does not support ping by design if [[ $1 != "--ci" ]] && ! ping -q -c 1 -W 1 google.com > /dev/null; then @@ -39,6 +54,8 @@ if apt list pylon --installed | grep -q $PYLON_VERSION; then echo "Pylon driver $PYLON_VERSION is already installed." else echo "Pylon driver $PYLON_VERSION is not installed. Installing..." + # Check if the OS is the required ubuntu version + check_os_is_required_ubuntu_version # Check if we have an internet connection check_internet_connection "$1" # Check if the url exist diff --git a/scripts/setup.sh b/scripts/setup.sh index 90fed54d7..5a4f2dfb8 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -4,7 +4,8 @@ set -eEuo pipefail # static/global variables DIR="$(dirname "$(readlink -f "$0")")" BRANCH="${1:-main}" -REPO_URL="git@github.com:bit-bots/bitbots_main.git" +REPO_URL_SSH="git@github.com:bit-bots/bitbots_main.git" +REPO_URL_HTTPS="https://github.com/bit-bots/bitbots_main.git" ask_question() { while true; do @@ -26,16 +27,21 @@ setup_repo() { echo "Setting up bitbots_main repository..." if (( in_repo )); then - cd "$meta_dir" || exit + cd "$main_dir" || exit git checkout "$BRANCH" else if [[ ! -d "$PWD/bitbots_main" ]]; then - git clone "$REPO_URL" + echo "Cloning repository bitbots_main..." + # Try to clone via SSH first, fall back to HTTPS if that fails + if ! git clone "$REPO_URL_SSH"; then + echo "SSH clone failed, trying HTTPS..." + git clone "$REPO_URL_HTTPS" + fi git checkout "$BRANCH" fi - meta_dir="$(realpath "$PWD/bitbots_main")" - cd "$meta_dir" || exit + main_dir="$(realpath "$PWD/bitbots_main")" + cd "$main_dir" || exit fi echo "Installing dependencies..." @@ -45,14 +51,21 @@ setup_repo() { setup_host() { echo "Setting up system dependencies not covered by pixi. This may require sudo rights. For non-Ubuntu systems, please install the required packages manually." if (( has_sudo )); then - $meta_dir/scripts/make_basler.sh + $main_dir/scripts/make_basler.sh + basler_installed=1 fi } build_repository() { - echo "Running full colcon build..." + echo "Running full build..." set +u + + # Append "--packages-skip bitbots_basler_camera" to the build command if setup_host was skipped or failed + if (( basler_installed )); then $HOME/.pixi/bin/pixi run build + else + $HOME/.pixi/bin/pixi run build --packages-skip bitbots_basler_camera + fi } has_sudo=0 @@ -63,13 +76,15 @@ if (( ! has_sudo )); then echo "Because, you don't have sudo rights, no host dependencies will be installed." fi +basler_installed=0 + in_repo=1 -meta_dir="$(realpath "$DIR/../")" -if [[ ! -d "$meta_dir/.git" ]]; then +main_dir="$(realpath "$DIR/../")" +if [[ ! -d "$main_dir/.git" ]]; then in_repo=0 fi -setup_ros +setup_pixi setup_repo setup_host build_repository diff --git a/src/bitbots_misc/bitbots_docs/CMakeLists.txt b/src/bitbots_misc/bitbots_docs/CMakeLists.txt index 08488f310..f4b595c9e 100644 --- a/src/bitbots_misc/bitbots_docs/CMakeLists.txt +++ b/src/bitbots_misc/bitbots_docs/CMakeLists.txt @@ -7,9 +7,9 @@ find_package(ament_cmake REQUIRED) # then, we can't build the documentation in this package file(COPY files DESTINATION ${CMAKE_INSTALL_PREFIX}/share/${PROJECT_NAME}) -# we cannot use the compiled catkin package of bitbots_docs since that would -# require this package to depend on itself. therefore we need to compile the sub -# cmake file ourselves and include it manually +# we cannot use the compiled package of bitbots_docs since that would require +# this package to depend on itself. therefore we need to compile the sub cmake +# file ourselves and include it manually configure_file(cmake/enable_bitbots_docs.cmake.in ${CMAKE_BINARY_DIR}/enable_bitbots_docs.cmake @ONLY) include(${CMAKE_BINARY_DIR}/enable_bitbots_docs.cmake) diff --git a/src/bitbots_misc/bitbots_docs/cmake/enable_bitbots_docs.cmake.in b/src/bitbots_misc/bitbots_docs/cmake/enable_bitbots_docs.cmake.in index 2618e4b1e..7de40f667 100644 --- a/src/bitbots_misc/bitbots_docs/cmake/enable_bitbots_docs.cmake.in +++ b/src/bitbots_misc/bitbots_docs/cmake/enable_bitbots_docs.cmake.in @@ -1,5 +1,5 @@ function(enable_bitbots_docs) - # create directories neccessary for sphinx + # create directories necessary for sphinx file(MAKE_DIRECTORY ${CMAKE_SOURCE_DIR}/docs/_build/doxyoutput) file(COPY @CMAKE_INSTALL_PREFIX@/share/bitbots_docs/files/_static DESTINATION ${CMAKE_SOURCE_DIR}/docs) diff --git a/src/bitbots_misc/bitbots_docs/docs/_static/bitbots_cpp_style.xml b/src/bitbots_misc/bitbots_docs/docs/_static/bitbots_cpp_style.xml deleted file mode 100644 index 9c98e123f..000000000 --- a/src/bitbots_misc/bitbots_docs/docs/_static/bitbots_cpp_style.xml +++ /dev/null @@ -1,59 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - diff --git a/src/bitbots_misc/bitbots_docs/docs/_static/bitbots_python_style.xml b/src/bitbots_misc/bitbots_docs/docs/_static/bitbots_python_style.xml deleted file mode 100644 index e94f32a8c..000000000 --- a/src/bitbots_misc/bitbots_docs/docs/_static/bitbots_python_style.xml +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/src/bitbots_misc/bitbots_docs/docs/index.rst b/src/bitbots_misc/bitbots_docs/docs/index.rst index a79426861..e4911a946 100644 --- a/src/bitbots_misc/bitbots_docs/docs/index.rst +++ b/src/bitbots_misc/bitbots_docs/docs/index.rst @@ -1,10 +1,9 @@ Welcome Bit-Bots main documentation! -================================================ +==================================== -This is the main page of `Hamburg Bit-Bots `_ documentation. Feel free to poke around -and see if you can find something. +This is the main page of `Hamburg Bit-Bots `_ documentation. -If you want to take a look at the code, our Github Organisation is also named `Bit-Bots +If you want to take a look at the code, our GitHub Organisation is also named `Bit-Bots `_. The main repository is `bitbots_main `_. @@ -34,7 +33,7 @@ The main repository is `bitbots_main ` .. toctree:: :maxdepth: 1 :glob: - :caption: Electronics + :caption: Electronics Wolfgang manual/hardware/electronics/* @@ -42,7 +41,7 @@ The main repository is `bitbots_main ` .. toctree:: :maxdepth: 1 :glob: - :caption: Mechanics + :caption: Mechanics Wolfgang manual/hardware/mechanics/* diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/screws.rst b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/screws.rst index f7c68c0ea..7e3fe099d 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/screws.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/screws.rst @@ -1,11 +1,15 @@ -=============== +====== Screws -=============== +====== Wolfgang -=============== +======== + +**NOTE: This is outdated and lacks some screws that were added later. Use with caution.** + By Position -------------- +----------- + +----------------------------------------+----------+--------+------------+ | Position | Type | Amount | Per Robot | | | | | | diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/software/coding_style.rst b/src/bitbots_misc/bitbots_docs/docs/manual/software/coding_style.rst index 2e788e170..d450f0a12 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/software/coding_style.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/software/coding_style.rst @@ -1,68 +1,29 @@ Coding Style ============ -Because we value maintainability and readability of our codebase, we have chosen to program according to the following -style guides. +To maintain a consistent coding style throughout the codebase, we use automatic formatting tools. +For this, we use `pre-commit `_ hooks that automatically format the code when a commit is made. +Our configuration can be found in the ``.pre-commit-config.yaml`` file in the root of the repository. +Continuous Integration (CI) also checks if the code is formatted correctly. -Python ------- +Setting up pre-commit +--------------------- -Our Python guide is based on `Google's style `_ with the following -adaptions: +.. code-block:: bash -* **3.2** - Instead of an 80 character maximum line length we do 120 characters. -* **3.8.2** - Since we have a _LICENSE_ file in every repository we refrain from including license boilerplate in every file. -* as a docstring format we use `reST `_. + pre-commit install -PyCharm Integration -~~~~~~~~~~~~~~~~~~~ +Running pre-commit manually +--------------------------- -* Go to File > Settings > Editor > Code Style. Click the gear icon and select Import Scheme > IntelliJ Idea code style XML. - Download :download:`our python style` and select it. Choose a name to store it. -* Make sure to select all python code inspections in Editor > Inspections > Python. +If you want to run pre-commit manually on all files, you can use the following command: -VSCode Integration -~~~~~~~~~~~~~~~~~~ -Install the Python extension. -Add the following lines to your settings.json ($HOME/.config/Code/User/settings.json) +.. code-block:: bash -.. code-block:: json + pixi run format - "python.formatting.provider": "yapf", - "python.formatting.yapfArgs": [ - "--style={based_on_style: google, column_limit: 120}" - ], - "editor.formatOnType": true, - "editor.formatOnPaste": true, - - - -C++ ---- - -Our C++ guide is based on the `ROS C++ Style Guide `_ except that our ``{`` are not -on a new line. - -CLion Integration -~~~~~~~~~~~~~~~~~~~ - -* Go to File > Settings > Editor > Code Style. Click the gear icon and select Import Scheme > IntelliJ Idea code style XML. - Download :download:`our cpp style` and select it. Choose a name to store it. -* Make sure to select all python code inspections in Editor > Inspections > C/C++. - -VSCode Integration -~~~~~~~~~~~~~~~~~~ -Install the C/C++ extension. -Add the following lines to your settings.json ($HOME/.config/Code/User/settings.json) - -.. code-block:: json - - "editor.formatOnType": true, - "editor.formatOnPaste": true, - "C_Cpp.clang_format_fallbackStyle": "{ BasedOnStyle: Google, AccessModifierOffset: -2, ConstructorInitializerIndentWidth: 2, AlignEscapedNewlinesLeft: false, AlignTrailingComments: true, AllowAllParametersOfDeclarationOnNextLine: false, AllowShortIfStatementsOnASingleLine: false, AllowShortLoopsOnASingleLine: false, AllowShortFunctionsOnASingleLine: None, AlwaysBreakTemplateDeclarations: true, AlwaysBreakBeforeMultilineStrings: true, BreakBeforeBinaryOperators: false, BreakBeforeTernaryOperators: false, BreakConstructorInitializersBeforeComma: false, BinPackParameters: true, ColumnLimit: 120, ConstructorInitializerAllOnOneLineOrOnePerLine: true, DerivePointerBinding: false, PointerBindsToType: true, ExperimentalAutoDetectBinPacking: false, IndentCaseLabels: true, MaxEmptyLinesToKeep: 1, NamespaceIndentation: None, ObjCSpaceBeforeProtocolList: true, PenaltyBreakBeforeFirstCallParameter: 19, PenaltyBreakComment: 60, PenaltyBreakString: 1, PenaltyBreakFirstLessLess: 1000, PenaltyExcessCharacter: 1000, PenaltyReturnTypeOnItsOwnLine: 90, SpacesBeforeTrailingComments: 2, Cpp11BracedListStyle: true, Standard: Auto, IndentWidth: 2, TabWidth: 2, UseTab: Never, IndentFunctionDeclarationAfterType: false, SpacesInParentheses: false, SpacesInAngles: false, SpaceInEmptyParentheses: false, SpacesInCStyleCastParentheses: false, SpaceAfterControlStatementKeyword: true, SpaceBeforeAssignmentOperators: true, ContinuationIndentWidth: 4, SortIncludes: false, SpaceAfterCStyleCast: false, BreakBeforeBraces: Custom, BraceWrapping: {AfterClass: 'false', AfterControlStatement: 'false', AfterEnum : 'false', AfterFunction : 'false', AfterNamespace : 'false', AfterStruct : 'false', AfterUnion : 'false', BeforeCatch : 'false', BeforeElse : 'false', IndentBraces : 'false'}}", - -Git ---- +Git Commit conventions +====================== We also have some conventions about how we want to use git. They are as follows: diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/testing/competition_preparation.rst b/src/bitbots_misc/bitbots_docs/docs/manual/testing/competition_preparation.rst index 2c8babddf..b2a441d49 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/testing/competition_preparation.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/testing/competition_preparation.rst @@ -14,7 +14,7 @@ When Powered Off * Inspect for head wobbling * Check camera cables for hard bends * Check if shoulders are bent -* Inspect NUC power connectors +* Inspect PC power connectors Before Powering On ------------------ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_motion.rst b/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_motion.rst index 28b98784a..3b85f0a5c 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_motion.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_motion.rst @@ -48,7 +48,7 @@ Easiest way to do both, is to use the following script: ros2 run bitbots_bringup check_robot.py -Alternativly, you can do it manually by following the following steps. +Alternatively, you can do it manually by following the following steps. #. Test Kick on Robot: .. code-block:: bash diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_robot_hardware.rst b/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_robot_hardware.rst index 4b8b15680..fa19d077f 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_robot_hardware.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_robot_hardware.rst @@ -9,8 +9,8 @@ Preliminaries Do the test in the provided order, to find out which part is faulty. -#. Use robot compile to flash correct version on robot -#. Put robot in a safe spot, on a rope hanging from the ceiling +#. Deploy the latest software to the robot +#. Put robot in a safe spot, e.g. on a rope hanging from the ceiling #. Check if all cables are correctly connected #. Open diagnostic view in rqt, it will provide a lot of information diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/testing/testing.rst b/src/bitbots_misc/bitbots_docs/docs/manual/testing/testing.rst index 4f0ce8dd0..1fc78ae26 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/testing/testing.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/testing/testing.rst @@ -60,17 +60,24 @@ The next step is to check if the package actually starts without crashing instan A part of this is that a launch file exists. Testing in Simulation ------------------------------------------------- +--------------------- We can test with values closer to real data if we do not use random data from humans, but with simulated data. We mainly use Webots for simulation. It offers us two possibilities. -:code:ros2 launch bitbots_bringup simulator_teamplayer.launch :=false/true +.. code-block:: bash + +ros2 launch bitbots_bringup simulator_teamplayer.launch :=false/true + Starts the simulator with designated params. -:code:ros2 launch bitbots_bringup highlevel.launch :=true/false + +.. code-block:: bash + +ros2 launch bitbots_bringup highlevel.launch :=true/false + Starts high-level software (Gamecontroller, Teamcomm, Behavior, Vision, Localization, Pathfinding) Testing on the robot (tested_robot) @@ -88,7 +95,7 @@ By our definition software is considered stable if it has been used in multiple What to do when changing a package? -==================================================== +=================================== Even when only small changes are applied to the master branch, the package has to be tested again to keep its test status. If the package is not tested again or only partially tested the test status has to be adapted to 'unknown' or the reached test state. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/competition_wifi.rst b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/competition_wifi.rst index 219a60ba6..8b1f461f4 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/competition_wifi.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/competition_wifi.rst @@ -3,7 +3,7 @@ Configuration of competition Wi-Fi At a competition, there will be different WiFi networks for each field. These can be setup with our ansible playbook for the robots. -This is done by editing the `group_vars/robots.yml `_ config variables e.g.: +This is done by editing the `group_vars/robots.yml `_ config variables e.g.: .. code-block:: yaml diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/configure_and_flash_robot.rst b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/configure_and_flash_robot.rst index ee8938382..33305fba9 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/configure_and_flash_robot.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/configure_and_flash_robot.rst @@ -1,11 +1,13 @@ -Configure and Flash a robot -=========================== +Configure and Deploy to a robot +=============================== -This section describes how to fully configure and flash a robot with a configured OS and your current software to prepare it for games. +This section describes how to fully configure and deploy your current software to a robot for game preparation. Robots ------ +We have multiple robots in our team, each with their own hostname and IP address. + .. note:: Current status as of September 2023: @@ -25,14 +27,51 @@ Robots | Rose | nuc6 | 172.20.1.16 | 172.20.4.16 | +--------+----------+-------------+-------------+ -Flashing --------- +Configuration with Ansible +-------------------------- + +Requirements +~~~~~~~~~~~~ + +- Ability to connect via SSH to the robot(s) +- Have our `ansible repo `_ checked out + +Configure the robot OS with ansible +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Our Ansible setup is able to configure the following aspects of the robot: + +- Configuration of kernel type and kernel/boot parameters +- Configuration of low level system parameters for better performance +- Setup/Configuration of the ``bitbots`` user account on the robot +- Network/IP configuration including: + - Configuration of competition Wi-Fi networks (see :doc:`competition_wifi`) + - Configuration of USB-Ethernet adapter as slave of a bridge interface, to allow for removal without losing the interface utilized by ros/dds + - Configuration of custom MTU of 9000 (jumbo frames) for Ethernet connection to the basler camera +- Installation and configuration of ROS and DDS +- Configuration of Vulkan packages/drivers + +To run the whole setup on a specific robot execute the following in the ansible repository folder: + +.. code-block:: bash -Flashing is the process of preparing a robot for the next game and starting the correct software. + ansible-playbook ./playbooks/setup_robots.yml --ask-become-pass --limit + +If you don't have access to the secret git-crypt data you can add ``--skip-tags git_crypt`` to the command. + +Ansible will execute the playbook with the ``bitbots`` user on the robots and will ask for its password to be able to utilize ``sudo``. .. note:: Does DNS not resolve ``nuc*``? See :doc:`configure_hostnames` to fix this. +Deployment +---------- + +Deployment is the process of preparing a robot for the next game and starting the correct software. + +.. note:: + Does DNS not resolve the robot name or ``nuc*``? See :doc:`configure_hostnames` to fix this. + At a competition, follow these steps: #. **Configure Wi-Fi networks for fields:** @@ -41,7 +80,7 @@ At a competition, follow these steps: #. **Checkout the latest code:** In your local `bitbots_main `_ repo run: - #. Check that you are on the ``master`` branch + #. Check that you are on the ``main`` branch #. ``git pull`` to get the latest changes #. **Sync, configure, compile and launch software:** @@ -51,7 +90,7 @@ At a competition, follow these steps: pixi run deploy - This does the 5 following tasks: + This does the following tasks: - Synchronize/Copy the current state of your local bitbots_main directory to the robot(s) - Install necessary dependencies on the robot(s) - Configure game specific settings and the Wi-Fi connection on the robot(s) @@ -73,42 +112,3 @@ At a competition, follow these steps: #. **Profit!** The robot is now ready play! - - -Ansible Configuration ---------------------- - -Requirements -~~~~~~~~~~~~ - -- Ability to connect via SSH to the robot(s) -- Have our `ansible repo `_ checked out - -Configure the robot OS with ansible -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Our Ansible setup is able to configure the following aspects of the robot: - -- Configuration of kernel type and kernel/boot parameters -- Configuration of low level system parameters for better performance -- Setup/Configuration of the ``bitbots`` user account on the robot -- Network/IP configuration including: - - Configuration of competition Wi-Fi networks (see :doc:`competition_wifi`) - - Configuration of USB-Ethernet adapter as slave of a bridge interface, to allow for removal without losing the interface utilized by ros/dds - - Configuration of custom MTU of 9000 (jumbo frames) for Ethernet connection to the basler camera -- Installation and configuration of ROS and DDS -- Configuration of Vulkan packages/drivers - -To run the whole setup on a specific robot execute the following in the ansible repository folder: - -.. code-block:: bash - - ansible-playbook ./playbooks/setup_robots.yml --ask-become-pass --limit - -if you dont have access to the secret git-crypt data you can add ``--skip-tags git_crypt`` to the command. - -Ansible will execute the playbook with the ``bitbots`` user on the robots and will ask for its password to be able to utilize ``sudo``. - -.. note:: - Does DNS not resolve ``nuc*``? See :doc:`configure_hostnames` to fix this. - diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/install_software_ros2.rst b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/installation.rst similarity index 77% rename from src/bitbots_misc/bitbots_docs/docs/manual/tutorials/install_software_ros2.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/tutorials/installation.rst index 641fb450c..bbc63ee3b 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/install_software_ros2.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/installation.rst @@ -1,15 +1,14 @@ -Software installation with ROS2 -=============================== +Software installation guide +=========================== In this tutorial, we will learn how to install all dependencies and build our software stack. -You might want to look at the :doc:`vscode-dev-container` tutorial, if you want to use a preconfigured development environment with Visual Studio Code and devcontainers. - **TLDR**: single command setup ------------------------------ -**Prerequirements** -- You have an existing Github account and added a SSH key to your account +**Prerequisites** + +- You have an existing GitHub account and added a SSH key to your account. If you have not previously set up any of our software stack, you can use the following command to install and setup everything in one go: @@ -28,7 +27,7 @@ Manual steps with in depth explanation We mainly develop and test our software on Ubuntu so we recommend using Ubuntu for development as well. Due to the use of pixi other distributions as well as Mac OS might work as well, but might require some tweaks. -Alternatively you can use a devcontainer :doc:`vscode-dev-container`, with a preconfigured environment and follow those instructions, as these docs do not apply to the devcontainer. +Alternatively you can use a devcontainer :doc:`vscode-dev-container`, with a pre-configured environment and follow those instructions, as these docs do not apply to the devcontainer. **1. Install Pixi** @@ -41,9 +40,9 @@ Run the following command to install pixi for your user: **2. Download our software** -- Create a GitHub account, if not already done (see `here `_ for further information) +- Create a GitHub account, if not already done (see `here `_ for further information) - Add your SSH key to GitHub to access and sync our repositories - - If you don't know what I am talking about or you don't yet have a SSH key, follow this guide: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys + - If you don't know what I am talking about or you don't yet have a SSH key, follow `this guide `_. - Go to your account settings and add your SSH key (the ``.pub`` file) to `GitHub `_ - Now, you can clone (download) our main code repository (repo) called `bitbots_main `_: - Open a terminal and go to the directory where you want to download our code, e.g. ``~/git/bitbots/`` @@ -55,7 +54,7 @@ Run the following command to install pixi for your user: Now that you have downloaded the code, you need to build it. A number of dependencies will be installed automatically during the build process. -Make sure you have about 10 GB of free disk space available. +Make sure you have about **10 GB of free disk space** available. Run the following command in the ``bitbots_main`` directory to build the software: .. code-block:: bash @@ -63,11 +62,11 @@ Run the following command in the ``bitbots_main`` directory to build the softwar pixi run build --packages-skip bitbots_basler_camera The compilation of the basler camera driver is skipped, as it requires the Pylon SDK to be installed manually. -If you need the basler camera driver, install the Pylon SDK manually or run `bash scripts/make_basler.sh` if you are using Ubuntu 22.04 and have root access. +If you need the basler camera driver, install the Pylon SDK manually or run `bash scripts/make_basler.sh` if you are using Ubuntu 24.04 and have root access. -Notes ------ +Legacy install methods +---------------------- Custom docker setup Before utilizing a devcontainer, we used a custom docker setup for ROS 2 development. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/lowlevel.rst b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/lowlevel.rst index cbe5de965..6bc2b6381 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/lowlevel.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/lowlevel.rst @@ -1,8 +1,6 @@ Bitbots Lowlevel ================ -`Github repository `_ - What do the low level packages do? ---------------------------------- @@ -40,9 +38,6 @@ When crimping new cables or when connecting a logic analyzer, it is important to The cables for TTL only have three wires: Ground, VCC and data. For the correct crimping, the same as for the RS-485 cables applies. - -| - .. figure:: lowlevel/pinouts.jpg This figure shows the pinouts of the different connectors we use. @@ -153,10 +148,12 @@ The corresponding ROS node can be launched with `roslaunch bitbots_ros_control r Help, I have a problem! ----------------------- +Also consider our documentation at :doc:`../testing/test_robot_hardware` for general robot hardware troubleshooting. + Error Opening Serial Port ~~~~~~~~~~~~~~~~~~~~~~~~~ -If you encounter the message "Error opening serial port", no connection between the NUC and the CORE board could be established. +If you encounter the message "Error opening serial port", no connection between the PC and the CORE board could be established. Therefore your first instinct should be checking whether the cable is plugged in correctly. If this does not solve the problem, you can check whether the board can be found by using `lsusb` (look for the "leaf" entry). You can further investigate this by using `ls /dev/`. You should find the devices "/dev/ttyUSB0" through "/dev/ttyUSB3", one for each of the four busses. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/vscode-ros2.rst b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/vscode-ros2.rst index 5eb4261ae..a4ae8d124 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/vscode-ros2.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/vscode-ros2.rst @@ -3,17 +3,17 @@ Setup VSCode with ROS2 ====================== Open a terminal. -Navigate to your colcon workspace. +Navigate to your bitbots_main workspace. -Source ros +Activate the pixi environment: -`source /opt/ros/jazzy/setup.zsh` +`pixi shell` Open VSCode `code .` -Install the ROS extension (from Microsoft). +Install the `Robotics Developer Extension `_. You should see a `ROS2.jazzy` in the lower left corner. Now you should be able to build the code with `Ctrl+Shift+B` diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/cl_simulation_testing_setup.rst b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/webots_simulation_testing.rst similarity index 57% rename from src/bitbots_misc/bitbots_docs/docs/manual/tutorials/cl_simulation_testing_setup.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/tutorials/webots_simulation_testing.rst index 7b25661ce..45a12a023 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/cl_simulation_testing_setup.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/webots_simulation_testing.rst @@ -1,29 +1,13 @@ -User CL Simulation Testing Setup +Webots Simulation Testing Setup ================================ -This setup is very similar to the tutorial on setting up a local environment for -development documented in our `documentation `_. +**1. Software installation** -As such you can lookup some of the needed requirements there. +Follow our `software installation guide `_ to install the software on the CL. -**0. Requirements** +TODO: Install webots (see discussion in ansible issue) -- have an LDAP mafiasi account for access to the CLs - -**1. Setup and download our software** - -- SSH into the ``cl0*`` with your mafiasi user -- Add your SSH key to GitHub to access and sync our repositories - - If you don't know what I am talking about or you don't yet have a SSH key, follow this guide: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys - - Go to your account settings and add your SSH key (the ``.pub`` file) to `GitHub `_ -- Make sure you have [pixi](https://pixi.sh) installed for your user. -- Setup bitbots_main in your home directory - -.. code-block:: bash - git clone git@github.com:bit-bots/bitbots_main.git && cd bitbots_main - pixi run build - -**3. Run Webots Simulation** +**2. Run Webots Simulation** We can start the Webots simulator with the following command: ``pixi run ros2 launch bitbots_bringup simulator_teamplayer.launch game_controller:=false`` @@ -41,7 +25,7 @@ we will simulate the current gamestate by our own script (in another terminal): Which allows us to simulate the current gamestate and different phases of the game. Now everything is ready for some simulation testing. -**4. Testing and Debugging** +**3. Testing and Debugging** By changing the simulated gamestate and seeing how the robot reacts, we can test our behavior. If there are issues with the robots behavior, they most likely have to do with DSD configuration or different diff --git a/src/bitbots_misc/bitbots_docs/package.xml b/src/bitbots_misc/bitbots_docs/package.xml index 759323129..fc7310f70 100644 --- a/src/bitbots_misc/bitbots_docs/package.xml +++ b/src/bitbots_misc/bitbots_docs/package.xml @@ -5,22 +5,15 @@ 1.1.0 Includes main Bit-Bots documentation and provides CMake helper functions to ease the creation of documentation - Finn-Thorben Sell - Hamburg Bit-Bots - MIT - + Hamburg Bit-Bots Hamburg Bit-Bots ament_cmake python3-sphinx-rtd-theme python3-breathe - - - unknown - - ament_cmake - + ament_cmake +