diff --git a/src/bitbots_misc/bitbots_docs/docs/conf.py b/src/bitbots_misc/bitbots_docs/docs/conf.py index 811833e16f..18497aabb4 100644 --- a/src/bitbots_misc/bitbots_docs/docs/conf.py +++ b/src/bitbots_misc/bitbots_docs/docs/conf.py @@ -88,7 +88,7 @@ def count_files(): # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. diff --git a/src/bitbots_misc/bitbots_docs/docs/index.rst b/src/bitbots_misc/bitbots_docs/docs/index.rst index e4911a946b..e632e6b628 100644 --- a/src/bitbots_misc/bitbots_docs/docs/index.rst +++ b/src/bitbots_misc/bitbots_docs/docs/index.rst @@ -9,41 +9,48 @@ The main repository is `bitbots_main ` .. toctree:: :maxdepth: 1 - :glob: - :caption: Tutorials: + :caption: Getting Started: - manual/tutorials/* + manual/getting_started/setup + manual/getting_started/software_overview + manual/getting_started/simulation_testing .. toctree:: :maxdepth: 1 - :glob: - :caption: Testing: - - manual/testing/* - + :caption: Physical Robot: + + manual/physical_robot/robots + manual/physical_robot/setup_robot + manual/physical_robot/competition_wifi + manual/physical_robot/piplus_hardware + manual/physical_robot/starting_robot + manual/physical_robot/connecting + manual/physical_robot/testing_robot + manual/physical_robot/extrinsic_calibration + manual/physical_robot/hardware_checklist + manual/physical_robot/configure_launch + manual/physical_robot/test_robot_hardware + manual/physical_robot/lowlevel .. toctree:: :maxdepth: 1 - :glob: - :caption: Software - - manual/software/* + :caption: Development: + manual/development/development_guidelines + manual/development/how_to_document + manual/development/testing + manual/development/rl_models .. toctree:: :maxdepth: 1 - :glob: - :caption: Electronics Wolfgang - - manual/hardware/electronics/* + :caption: Glossary: + manual/glossary -.. toctree:: - :maxdepth: 1 - :glob: - :caption: Mechanics Wolfgang - - manual/hardware/mechanics/* +.. todo:: + Rework of the public documentation (see issue #1037): replace the plain link + to the default package directory index below with a curated list of all + packages that have non-empty documentation. `Package Documentations `_ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/software/coding_style.rst b/src/bitbots_misc/bitbots_docs/docs/manual/development/development_guidelines.rst similarity index 66% rename from src/bitbots_misc/bitbots_docs/docs/manual/software/coding_style.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/development/development_guidelines.rst index d450f0a12f..7668a11e26 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/software/coding_style.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/development/development_guidelines.rst @@ -1,5 +1,25 @@ +Development Guidelines +====================== + +.. todo:: + Rework of the public documentation (see issue #1037): flesh out the sections + below into full prose and link to the relevant tooling. + +How We Develop +-------------- + +- Create a branch named ``feature/*``, ``fix/*``, or ``docs/*``. +- Always create a pull request for anything that may be merged. If it is not + finished yet, create a draft pull request. +- Once it is ready, ask for review from the relevant authors and respond to and + fix those comments. +- CI needs to pass. +- If you do not have the capacity to make a pull request right now, open an + issue instead. +- Add pull requests and issues to the project board. + Coding Style -============ +------------ 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. @@ -7,14 +27,14 @@ Our configuration can be found in the ``.pre-commit-config.yaml`` file in the ro Continuous Integration (CI) also checks if the code is formatted correctly. Setting up pre-commit ---------------------- +~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash pre-commit install Running pre-commit manually ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to run pre-commit manually on all files, you can use the following command: @@ -23,7 +43,7 @@ If you want to run pre-commit manually on all files, you can use the following c pixi run format 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/tutorials/Docs-How-To.rst b/src/bitbots_misc/bitbots_docs/docs/manual/development/how_to_document.rst similarity index 99% rename from src/bitbots_misc/bitbots_docs/docs/manual/tutorials/Docs-How-To.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/development/how_to_document.rst index adbe2078cc..51bde84d5a 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/Docs-How-To.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/development/how_to_document.rst @@ -16,6 +16,8 @@ The correct version of the extentions must be installed. pip3 install exhale --user +.. _build_documentation: + How to build the documentation ============================== diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/rl_models.rst b/src/bitbots_misc/bitbots_docs/docs/manual/development/rl_models.rst similarity index 92% rename from src/bitbots_misc/bitbots_docs/docs/manual/tutorials/rl_models.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/development/rl_models.rst index e29ce290df..6bc99964c5 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/rl_models.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/development/rl_models.rst @@ -2,6 +2,12 @@ Reinforcement Learning of Policies and Deployment ================================================= +.. todo:: + Rework of the public documentation (see issue #1037): this page lives in the + Development section. It is linked from + :doc:`../physical_robot/testing_robot` where the RL motion commands are + referenced. + We use several reinforcement learning frameworks to train policies for our robots. After the models have been trained we export them as onnx files which describe the neural network structure and weights. We use the bitbots_rl_motion policy execution framework to deploy the models on our robots. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/testing/testing.rst b/src/bitbots_misc/bitbots_docs/docs/manual/development/testing.rst similarity index 94% rename from src/bitbots_misc/bitbots_docs/docs/manual/testing/testing.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/development/testing.rst index 2da1cb1d80..bb2d190b9b 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/testing/testing.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/development/testing.rst @@ -2,6 +2,12 @@ How to Test =========== +.. todo:: + Rework of the public documentation (see issue #1037): this general testing + page is not explicitly placed in the new structure. Confirm whether it belongs + under "Development" (as kept here) or should be merged with + :doc:`../getting_started/simulation_testing`. + General Remarks =============== diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/installation.rst b/src/bitbots_misc/bitbots_docs/docs/manual/getting_started/setup.rst similarity index 87% rename from src/bitbots_misc/bitbots_docs/docs/manual/tutorials/installation.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/getting_started/setup.rst index 02d7bbfd46..ddf57bf8fe 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/installation.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/getting_started/setup.rst @@ -1,8 +1,18 @@ -Software installation guide -=========================== +Setup +===== In this tutorial, we will learn how to install all dependencies and build our software stack. +.. todo:: + Rework of the public documentation (see issue #1037): + + - This page should have the same content as the repository ``README.md``; our + install instructions are small enough to fully fit here. Keep the two in + sync. + - Mention that Zenoh is required for almost all of our software to run. + - Mention that all commands need to be run from inside ``pixi shell`` or with + ``pixi run``. + **TLDR**: single command setup ------------------------------ @@ -27,8 +37,6 @@ 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 pre-configured environment and follow those instructions, as these docs do not apply to the devcontainer. - **1. Install Pixi** We manage our development environment with `pixi `_, which makes setting up and using our software stack much easier. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/testing/sim_test.rst b/src/bitbots_misc/bitbots_docs/docs/manual/getting_started/simulation_testing.rst similarity index 94% rename from src/bitbots_misc/bitbots_docs/docs/manual/testing/sim_test.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/getting_started/simulation_testing.rst index 0d09cdd35d..78a38da0b0 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/testing/sim_test.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/getting_started/simulation_testing.rst @@ -6,7 +6,7 @@ Test Motion .. code-block:: bash - ros2 launch bitbots_mujoco_sim simulation.launch + ros2 launch bitbots_mujoco_sim simulator.launch ros2 launch bitbots_bringup motion_standalone.launch sim:=true To control walking of the robot, teleop needs to be startet as well: diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/launch_files.rst b/src/bitbots_misc/bitbots_docs/docs/manual/getting_started/software_overview.rst similarity index 80% rename from src/bitbots_misc/bitbots_docs/docs/manual/tutorials/launch_files.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/getting_started/software_overview.rst index b95da48b2c..a136ad829c 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/launch_files.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/getting_started/software_overview.rst @@ -1,6 +1,17 @@ -============== -Launch Scripts -============== +======================== +Global Software Overview +======================== + +.. todo:: + Rework of the public documentation (see issue #1037): this page should give a + global overview of our software. In addition to the bringup launch scripts + below, add: + + - A high level data flow diagram of the software stack. + - A list of all bitbots packages with a short description, grouped by topic. + +Bringup Launch Scripts +====================== Listed below are the most important launch files. You can display the arguments of the launch files in the terminal by using the command diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/glossary.rst b/src/bitbots_misc/bitbots_docs/docs/manual/glossary.rst new file mode 100644 index 0000000000..dea65050a3 --- /dev/null +++ b/src/bitbots_misc/bitbots_docs/docs/manual/glossary.rst @@ -0,0 +1,13 @@ +Glossary +======== + +.. todo:: + Rework of the public documentation (see issue #1037): collect the recurring + Bit-Bots and RoboCup terms used throughout this documentation and define them + here, using the reStructuredText ``glossary`` directive so that ``:term:`` + references can link to the definitions. + +.. glossary:: + + PiPlus + The current Bit-Bots humanoid robot platform. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/bitfoot.rst b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/bitfoot.rst deleted file mode 100644 index dddf9db43d..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/bitfoot.rst +++ /dev/null @@ -1,146 +0,0 @@ -======== -BitFoot -======== - -The BitFoot is the foot pressure sensor by the Hamburg Bit-Bots. -It features a higher update rate and higher resolution than the Rhoban ForceFoot_ on which it is based. - -This board measures four differential voltage signals from load cells. It connects to a RS485 or TTL Bus compatible with Dynamixel motors from Robotis. - -We managed to achieve a sensor update rate of 697Hz. The board itself can be read faster than 1kHz from the Dynamixel bus. - -Firmware, schematics, gerber files, and BOMs can be found in our git repository_: - -In a previous version, we used an STM32F103 microcontroller on a BluePill board. -Since we had some issues with the microcontrollers performance we switched to an ESP32. - -Because we did not want to redesign the analog part of the board, we designed an adapter board from the ESP32 to the BluePill pinout. - -The load cells we use are called TAL230A as described here: loadcell_. - - -.. _loadcell: http://www.htc-sensor.com/products/146.html -.. _ForceFoot: https://www.github.com/Rhoban/ForceFoot -.. _repository: https://www.github.com/bit-bots/bit_foot - -Software -======== - -Firmware --------- - -The firmware is uses the Arduino framework. We usually install it using the Arduino IDE. -The required libraries are: - -* `ADS126X `_ -* `Dynamixel2Arduino `_ - -For installing the build tools for the ESP32 refer to `espressif's documentation `_. - -For flashing a ESP32 Wroom (without development board) we recommend a `programming socket `_. - -Flash the board before soldering! - -ROS Control ------------ - -We developed a hardware interface that complies with the ros_control standard for the Wolfgang robot platform. -This includes a hardware interface for the BitFoot. Documentation for it can be found here: :doc:`../../tutorials/lowlevel` - -Strain Gauge Connection -======================= - -The strain gages should be connected as follows when using our ros_control based software: - -* P1: Back Right -* P2: Back Left -* P3: Front Right -* P4: Front Left - - -.. _Calibrating the Sensors: - -Calibrating the Sensors -======================= - -After the device has been connected to the DXL Bus, launch the hardware interface: - -:code:`roslaunch bitbots_ros_control ros_control_standalone.launch only_pressure:=true` - -Then run the calibration node: - -:code:`rosrun bitbots_ros_control pressure_calibration.py` - -The node will guide you through the process of calibrating the cleats. - -Register Table -============== - -+--------+--------+--------------------------+--------+---------+---------+-------------+ -| Adress | Length | Name | Access | Default | Type | Persistent? | -+========+========+==========================+========+=========+=========+=============+ -| 7 | 1 | :ref:`id` | rw | 101 | int8 | yes | -+--------+--------+--------------------------+--------+---------+---------+-------------+ -| 8 | 1 | :ref:`baud` | rw | 4 | int8 | yes | -+--------+--------+--------------------------+--------+---------+---------+-------------+ -| 36 | 4 | :ref:`sensor_0` | r | | float32 | | -+--------+--------+--------------------------+--------+---------+---------+-------------+ -| 40 | 4 | :ref:`sensor_1` | r | | float32 | | -+--------+--------+--------------------------+--------+---------+---------+-------------+ -| 44 | 4 | :ref:`sensor_2` | r | | float32 | | -+--------+--------+--------------------------+--------+---------+---------+-------------+ -| 48 | 4 | :ref:`sensor_3` | r | | float32 | | -+--------+--------+--------------------------+--------+---------+---------+-------------+ - -.. _DXL_BitFoot: - -DXL ---- - -**id**: Can be a value between 1 and 252. it is used to talk to the device over the Dynamixel bus. - -**baud**: Can be a value between 0 and 7 - -+-------+---------+--------+ -| value | baud | Tested | -+=======+=========+========+ -| 0 | 9,600 | no | -+-------+---------+--------+ -| 1 | 57,600 | no | -+-------+---------+--------+ -| 2 | 115,200 | no | -+-------+---------+--------+ -| 3 | 1M | no | -+-------+---------+--------+ -| 4 | 2M | yes | -+-------+---------+--------+ -| 5 | 3M | no | -+-------+---------+--------+ -| 6 | 4M | yes | -+-------+---------+--------+ -| 7 | 4.5M | no | -+-------+---------+--------+ - -We are reasonably certain that the other baud rates work as well since the ESP32 supports them. - -.. _Sensors: - -Sensors -------- - -**sensor_{0..3}**: Raw reading of the sensors differential voltage. Must be :ref:`calibrated` to give a meaningful reading. - -* sensor_0 = P4 -* sensor_1 = P3 -* sensor_2 = P2 -* sensor_3 = P1 - -.. figure:: img/bitfoot.jpeg - :scale: 20% - - The figure shows the circuit board of the BitFoot. The sensors P1-P4 can be seen. - -.. figure:: img/bitfoot_mounted.jpeg - :scale: 20% - - Mounted BitFoot on a robot diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/bitfoot.jpeg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/bitfoot.jpeg deleted file mode 100644 index 41e9cc3745..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/bitfoot.jpeg and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/bitfoot.svg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/bitfoot.svg deleted file mode 100644 index 391b5fe5be..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/bitfoot.svg +++ /dev/null @@ -1,6556 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - P1/sensor_3right_back - - - - P2/sensor_2left_back - - - - P3/sensor_1right_front - - - - P4/sensor_0left_front - - - - - - - diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/bitfoot_mounted.jpeg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/bitfoot_mounted.jpeg deleted file mode 100644 index 6cc90a7788..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/bitfoot_mounted.jpeg and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/constant_voltage.jpg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/constant_voltage.jpg deleted file mode 100644 index c92da57078..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/constant_voltage.jpg and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/core.png b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/core.png deleted file mode 100644 index 8c6cecbb56..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/core.png and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/core_bodge.png b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/core_bodge.png deleted file mode 100644 index ef7070492e..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/core_bodge.png and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/imu_back.jpg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/imu_back.jpg deleted file mode 100644 index 67fd6b9cfb..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/imu_back.jpg and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/imu_front_empty.jpg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/imu_front_empty.jpg deleted file mode 100644 index 949cccc3b0..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/imu_front_empty.jpg and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/imu_mounted.jpg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/imu_mounted.jpg deleted file mode 100644 index 6f5165ade7..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/imu_mounted.jpg and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/speaker_empty.png b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/speaker_empty.png deleted file mode 100644 index fa5a35e14e..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/speaker_empty.png and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/speaker_empty.svg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/speaker_empty.svg deleted file mode 100644 index f3dade261b..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/speaker_empty.svg +++ /dev/null @@ -1,247 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Power - - - - Audio In - - - - Audio Out - - - - - - - diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/speaker_mounted.jpg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/speaker_mounted.jpg deleted file mode 100644 index 88814d61ff..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/img/speaker_mounted.jpg and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/imu_dxl.rst b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/imu_dxl.rst deleted file mode 100644 index a5e49d6d9c..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/imu_dxl.rst +++ /dev/null @@ -1,327 +0,0 @@ -====================== -Bitbots IMU DXL Module -====================== - -`Github repository `_ - -.. list-table:: - - - * - .. figure:: img/imu_front_empty.jpg - :scale: 40% - - - .. figure:: img/imu_back.jpg - :scale: 40% - - - .. figure:: img/imu_mounted.jpg - :scale: 40% - - * - | IMU without buttons - | and LEDs (top side) - - | IMU in 3d printed case - | with RS485 connectors - | (bottom side) - - | IMU in 3d printed case - | with buttons and LEDs - | (top side) - -Features -======== - -* 12 Bit 3 axis gyroscope and 3 axis accelerometer (MPU6500 sensor) -* 1000 Hz update rate -* configurable range (250-2000 deg/sec and 2-16g) -* configurable onboard complementary `filter `_ -* gyroscope and accelerometer calibration procedure -* direct reading of orientation as quaternion -* connection via the Dynamixel bus -* WS2812b RGB LEDs -* 3 Buttons - - -Software -======== - -The software consists of two parts. Firstly the firmware which is installed on the ESP32 and -secondly (at least for us) the :ref:`ros_control` based diver to communicate with the board. -You can communicate to the board using the standard Dynamixel protocol version 2.0, if you wish to write your own hardware interface for it. -Version 1 may also work, but we did not test it. - - -Firmware --------- - -The firmware is uses the Arduino framework. We usually install it using the Arduino IDE. -The required libraries are: - -* `FastLED `_ -* `MPU9250/MPU6500 `_ on branch MPU6500 -* `Dynamixel2Arduino `_ - -For installing the build tools for the ESP32 refer to `espressif's documentation `_. - -For flashing a ESP32 Wroom (without development board) we recommend a `programming socket `_. - -If the board is already soldered, the programming header can be used. The square pin is pin 1 (+3V3). -Please refer to the schematic for the pinout. There is a :ref:`known issue` with this. - - -.. _ROS Control: - -ROS Control ------------ - -We developed a hardware interface that complies with the ros_control standard for the Wolfgang robot platform. -This includes a hardware interface for the IMU. Documentation for it can be found here: :doc:`../../tutorials/lowlevel` - - -.. _Known Issues: - -Known Issues -============ - -* The ESP32's UART1 is connected to the Dynamixel bus. It is also normally used for programming. - If the level shifter (U4) is installed, programming is not possible even with the programming header. -* Soldering the MPU6500 module on the IMU module is quite difficult. - We have used hot air and destroyed some modules with it. - - -RS485/TTL selection -=================== - -R1 and R2 should not be populated, if RS485 is used to communicate with the board. -They must be installed, if TTL is used. - - -Register Table -============== - -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| Adress | Length | Name | Access | Default | Type | Persistent | -+========+========+=====================================================+========+=========+=========+============+ -| 7 | 1 | :ref:`id` | rw | 241 | int8 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 8 | 1 | :ref:`baud` | rw | 4 | int8 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 10 | 4 | :ref:`led0` | rw | 0 | int8[4] | no | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 14 | 4 | :ref:`led1` | rw | 0 | int8[4] | no | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 18 | 4 | :ref:`led2` | rw | 0 | int8[4] | no | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 36 | 4 | :ref:`gyro_x` | r | | float32 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 40 | 4 | :ref:`gyro_y` | r | | float32 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 44 | 4 | :ref:`gyro_z` | r | | float32 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 48 | 4 | :ref:`accel_x` | r | | float32 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 52 | 4 | :ref:`accel_y` | r | | float32 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 56 | 4 | :ref:`accel_z` | r | | float32 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 60 | 4 | :ref:`quaternion_x` | r | | float32 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 64 | 4 | :ref:`quaternion_y` | r | | float32 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 68 | 4 | :ref:`quaternion_z` | r | | float32 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 72 | 4 | :ref:`quaternion_w` | r | | float32 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 76 | 1 | :ref:`button0` | r | | int8 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 77 | 1 | :ref:`button1` | r | | int8 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 78 | 1 | :ref:`button2` | r | | int8 | | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 102 | 1 | :ref:`gyro_range` | rw | 3 | int8 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 103 | 1 | :ref:`accel_range` | rw | 3 | int8 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 104 | 1 | :ref:`calibrate_gyro` | rw | 0 | int8 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 105 | 1 | :ref:`reset_gyro_calibration` | rw | 0 | int8 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 106 | 1 | :ref:`calibrate_accel` | rw | 0 | int8 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 107 | 1 | :ref:`reset_accel_calibration` | rw | 0 | int8 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 108 | 1 | :ref:`do_adaptive_gain` | rw | 0 | int8 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 109 | 1 | :ref:`do_bias_estimation` | rw | 0 | int8 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 110 | 4 | :ref:`accel_gain` | rw | 0.04 | float32 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 114 | 4 | :ref:`bias_alpha` | rw | 0.01 | float32 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 118 | 4 | :ref:`accel_calibration_threshold` | rw | 7.5 | float32 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 122 | 4 | :ref:`accel_bias_x` | rw | 0.0 | float32 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 126 | 4 | :ref:`accel_bias_y` | rw | 0.0 | float32 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 130 | 4 | :ref:`accel_bias_z` | rw | 0.0 | float32 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 134 | 4 | :ref:`accel_scale_x` | rw | 1.0 | float32 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 138 | 4 | :ref:`accel_scale_y` | rw | 1.0 | float32 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ -| 142 | 4 | :ref:`accel_scale_z` | rw | 1.0 | float32 | yes | -+--------+--------+-----------------------------------------------------+--------+---------+---------+------------+ - - -.. _DXL_IMU: - -DXL ---- - -**id**: Can be a value between 1 and 252. It is used to talk to the device over the Dynamixel bus. - -**baud**: Can be a value between 0 and 7 - -+-------+---------+--------+ -| value | baud | Tested | -+=======+=========+========+ -| 0 | 9,600 | no | -+-------+---------+--------+ -| 1 | 57,600 | no | -+-------+---------+--------+ -| 2 | 115,200 | no | -+-------+---------+--------+ -| 3 | 1M | no | -+-------+---------+--------+ -| 4 | 2M | yes | -+-------+---------+--------+ -| 5 | 3M | no | -+-------+---------+--------+ -| 6 | 4M | yes | -+-------+---------+--------+ -| 7 | 4.5M | no | -+-------+---------+--------+ - -We are reasonably certain that the other baud rates work as well, since the ESP32 supports them. - - -.. _LEDs_IMU: - -LEDs ----- - -**led{0,1,2}**: Byte order: RGB, 4th byte is ignored but reserved. - - -.. _IMU: - -IMU ---- - -**gyro_{x,y,z}**: Current measurement of the gyroscope in the respective axis in rad/s - -**accel_{x,y,z}**: Current measurement of the accelerometer in the respective axis in m/s^2 - -**quaternion_{x,y,z,w}**: Quaternion giving the orientation of the imu in respect to to ground. - - -.. _Buttons: - -Buttons -------- - -**button{0,1,2}**: Reading from the buttons, 1 when pressed. - - -.. _Ranges: - -Ranges ------- - -**gyro_range**: Can be a value between 0 and 3 - -+-------+-------------+ -| value | range | -+=======+=============+ -| 0 | ±250 deg/s | -+-------+-------------+ -| 1 | ±500 deg/s | -+-------+-------------+ -| 2 | ±1000 deg/s | -+-------+-------------+ -| 3 | ±2000 deg/s | -+-------+-------------+ - -**accel_range**: Can be a value between 0 and 3 - -+-------+--------+ -| value | range | -+=======+========+ -| 0 | ±2 g | -+-------+--------+ -| 1 | ±4 g | -+-------+--------+ -| 2 | ±8 g | -+-------+--------+ -| 3 | ±16 g | -+-------+--------+ - - -.. _IMU calibration: - -IMU calibration ---------------- - -**calibrate_gyro**: Setting this value to 1 causes the gyroscope to be calibrated, the module is unresponsive for around 2 seconds -This procedure should be performed when the IMU is not moving. -It should be done relatively frequently. -The gyro calibration is not persistent. - -**reset_gyro_calibration**: Resets the gyro calibration. Useful, if the gyro was accidentally calibrated while moving. - -**calibrate_accel**: Starts the :ref:`accelerometer calibration routine`. - -**reset_accel_calibration**: Resets the :ref:`accelerometer calibration`. -Be careful as it can be tedious to perform the calibration routine. - -**accel_calibration_threshold**: The threshold used for accelerometer :ref:`accelerometer calibration`. - -**accel_bias_{x,y,z}**: The bias (i. e. the offset from 0) calculated in the calibration routine. - -**accel_scale_{x,y,z}**: The scale factor calculated in the calibration routine. Should be relatively close to 1.0 after calibration. - - -.. _Complementary Filter: - -Complementary Filter --------------------- - -**do_adaptive_gain**: If 1, the gain is adapted to be weighted more if the IMU is in a steady state. - -**do_bias_estimation**: If 1, the bias of the gyroscope is estimated when the IMU is in a steady state. - -**accel_gain**: How much the orientation is influenced by the accelerometer. - -**bias_alpha**: In the bias estimation, how strongly the biases are adjusted if **do_bias_estimation** is 1 and the IMU is in a steady state. - - -.. _Accelerometer Calibration: - -Accelerometer Calibration -========================= - -It is necessary to calibrate the accelerometer once before using it. -For this, the accelerometer must be placed with the x,y, and z-axis pointing downwards and upwards once. -We have designed the 3D printed case for the board in such a way, that this is relatively easy. - -Before starting the calibration, you should check the accelerometer measurements. -For each of the axes pointing downwards or upwards the value should be at least 7.5 m/s^2. -If this is not the case, you need to lower the **accel_calibration_threshold**. - -To perform the calibration procedure follow this procedure: - -1. Place the IMU on one of the 6 sides -2. Set a 1 to the **calibrate_accel** register (``rosservice call /imu/calibrate_accel``, if you are using our software) -3. Wait until the IMU responds to reads again (or around 5 seconds) -4. Repeat for remaining 5 sides - -After the procedure, you should check the values in the **accel_scale** and **accel_bias** registers. -Scale should be really close to 1 and bias can, in our experience, deviate by 1-2 m/s^2. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/register_tables/bitfoot_registers.ods b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/register_tables/bitfoot_registers.ods deleted file mode 100644 index e6d40fcb2a..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/register_tables/bitfoot_registers.ods and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/register_tables/core_registers.ods b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/register_tables/core_registers.ods deleted file mode 100644 index 347cca3b21..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/register_tables/core_registers.ods and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/register_tables/imu_registers.ods b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/register_tables/imu_registers.ods deleted file mode 100644 index 1fa4c14cf5..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/register_tables/imu_registers.ods and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/speaker.rst b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/speaker.rst deleted file mode 100644 index a9c034b786..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/speaker.rst +++ /dev/null @@ -1,17 +0,0 @@ -======== -Speaker -======== - -The speaker consists of an amplifier and a speaker. -It is powered with USB (5V) and uses a normal headphone jack for the audio input. - -.. list-table:: - - * - .. figure:: img/speaker_empty.png - :scale: 40% - - - .. figure:: img/speaker_mounted.jpg - :scale: 40% - - * - Speaker with labeled connections - - Amplifier and speaker unit diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/wolfgang_constant_voltage.rst b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/wolfgang_constant_voltage.rst deleted file mode 100644 index a24c46c54a..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/wolfgang_constant_voltage.rst +++ /dev/null @@ -1,34 +0,0 @@ -========================= -Wolfgang Constant Voltage -========================= - -`Github repository `_ - -.. image:: img/constant_voltage.jpg - :width: 800 - -Wolfang Constant Voltage regulates the voltage of the battery to 15.4V (this may be configured however). - -We have observed that the motors behave very differently when supplied with different voltage. -This causes stability issues in basically all motions of the robot depending on the battery charging state. - -Therefore, we decided to solve this problem using a 6-cell LiPo battery which provides 22.2V-25.2V depending on how much it is discharged and regulate the voltage down to be usable by the motors. -The step-down converter is a `TDK-Lambda i7A4W033A033V-0C1-R `_. -This module can regulate up to 33A continously and 45A peak. -For our application, this is sufficient. -Several versions of the Board are available with differen heatsinks. -We found that the `i7A4W033A033V-0C1-R `_ does not get too warm during operation. -The version with a larger heatsink may be more efficient at the cost of weight. - -Previously, we have tested the `I6A24014A033V-001-R `_ -but have found that the current surge at the beginning of some motions caused by many motors trying to overcome the static friction, -and motions requiring many motors (e. g. standing up) triggers the overcurrent protection of the device. - -Schematics, board drawings and gerber files for production are available in the `GitHub repository `_. - -R3 configures the output voltage of the converter. Several relatively common values as well as the calculation for a desired voltage are given in the schematic. - -The SENSE header can be connected to an external ADC to measure the output voltage of the converter. The range is defined by the voltage divider R1 and R2. - -The input and output capacitors are chosen according to the datasheet of the converter. - diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/wolfgang_core.rst b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/wolfgang_core.rst deleted file mode 100644 index 770cc29c4f..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/electronics/wolfgang_core.rst +++ /dev/null @@ -1,316 +0,0 @@ -============= -Wolfgang CORE -============= - -`Github repository `_ - -.. image:: img/core.png - :width: 800 - -Features -======== - - -* Power over Ethernet (PoE) power source (for ethernet camera) -* Power regulation 5V ~5A (Odroid/Raspberry Pi), 9V 1A (network switch) -* Power source selection (Battery or power supply) -* Switching of power to Motors (Manual and through software) -* RS485/TTL on 4 Buses with theoretically up to 12 MBaud (4MBaud tested since thats what our Dynamixel motors support) -* Voltage (including Cell voltage for LiPos) and Current monitoring -* 3 RGB LEDS!!! - - -Software -======== - - -Firmware --------- - -Required Libraries: - -* `Dynamixel2Arduino `_ -* `FastLED `_ - -Installation instructions for the Teensy 4.0 for the Arduino IDE can be found `here `_. - -ROS Control ------------ - -We have written a ros_control hardware interface for the board. -You can use it or use it as a reference for your own hardware abstraction. -Documentation for it can be found here: :doc:`../../tutorials/lowlevel` - -Problems and Solutions -====================== - -V1.0 is unfortunately only 98% perfect. - -Reading of ttyUSB1 without Teensy ---------------------------------- - -Devices on ttyUSB3 can not be read when the Teensy is not installed or installed and not powered (see :ref:`Jumpers`) -since the !RE/DE pins of the Teensys transceiver are not pulled down. - -.. _Bodge Switch: - -Automatic Poweroff-Poweron Routine ----------------------------------- - -When software disables the power to the motors and the user turns off and on the power manually, it should be on. -To accomplish this, the Teensy has to read the power state of the manual switch. - -To achieve this the trace marked in red has to be cut (for example with an x-acto knife, make sure there is really no connection) -and a wire marked in green needs to be soldered. - -Additionally, R40 needs to be replaced by a lower valued resistor, otherwise the switch_power net will be pulled to ~1.68V while the next component requires a minimum of 2V to recognize this as a high input. A 1K resistor is recommended. - - -.. image:: img/core_bodge.png - :width: 800 - -Numbering of Dynamixel Buses ----------------------------- - -The number behind the name below the Molex SPOX Mini connectors is meant to show which ttyUSBX virtual device corresponds to which bus. -Due to a mixup it is wrong. - -Correct version: - -+-----------+----------+-----------+-------------+ -| ttyUSB0 | ttyUSB1 | ttyUSB2 | ttyUSB3 | -+===========+==========+===========+=============+ -| Right Leg | Left Leg | Head+IMUs | Teensy+Arms | -+-----------+----------+-----------+-------------+ - -Status LEDs -=========== - -The red round LED next to the manual switch indicated that the board is powered. If it is off even though the board is plugged in, the fuse might be blown. - -The green round LED next to it indicates if the motors and other devices on the Dynamixel bus are powered. - -The three RGB LEDs are set by software. - - -Power over Ethernet -=================== - -The board features a Power over Ethernet (PoE) power sourcing equipment (PSE). -To be more specific, it is a midspan, meaning it injects the power part of PoE onto the signal. -It basically works like a PoE injector which are widely available but in a much nicer form factor for a robot. - -The powered device should be plugged into the RJ45 port pointing to the top and the other device into the port pointing to the bottom. - -PoE works with 48V which means you should not lick it 😜. - -Power Regulation -================ - -There are two step down converters on the board to power other devices in the robot. -The 5V regulator can theoretically provide up to 10A but we have never tested it and it might need cooling or a heatsink for that. -In our case it used to power an ODROID XU4 which normally comes with a 4A power source (which it never really uses unless there are many power hungry USB devices plugged in). - -The 5V regulator also powers some of the electronics on the board such as the Teensy, the LEDs and the current sensor. - -A small 9V regulator is also on the board since the network switches we use in our robot run on 9V. - -9V and 5V are on the Molex Mini-Lock connector on the bottom left of the board. The pinout from left to right is: - -+-----+-----+-----+-----+ -| GND | GND | +5V | +9V | -+-----+-----+-----+-----+ - -.. _Power: - -Power Connectors and Power Source Selection -=========================================== - -There are two connectors meant to be used for soldering a connector (e.g. Tamiya or XT90) to connect a battery and power supply. - -They are located on the right above the Molex SPOX Mini connectors. -They are labeled as VBAT+ and VBAT- for the battery and VEXT+ and VEXT- for the external supply. While technically they are treated the same, -it is recommended to connect them in the correct order since only VEXT is measured and VBAT should be the same as the one connected to the balancer connector. -The batteries balancer connector should be connected to P2. Be careful when soldering P2 since it needs to be oriented correctly. -The GND pin is at the very bottom. If it is plugged in the other way, the Teensy will probably blow up 🤯. - -Both, a battery and a power supply, can be safely connected at the same time. -No energy is transfered from one to the other since there is a double Schottky diode (D2 on the bottom side) between them. -This can be useful when changing batteries but keeping the robot powered on using a power supply. - -While some energy is lost over D2, this simple solution has proven very robust. - - -Switching of power to Motors -============================ - -Power on the Dynamixel bus can be switched on and off using either the manual switch or through software. -If the manual switch is to the right, the power is off. If it is to the right, the power is on (if the software agrees). -The manual switch is an override, meaning when it is off, the teensy can not enable it. -If there is power on the Dynamixel bus the green round LED will be on. -If it is on when the switch is in the off position (to the right), the MOSFET Q1 is probably blown and needs replacement. -This may happen if there is a short circuit and the MOSFET is weaker than the fuse. - -When the power is turned off by software, but is on by the switch, -you can flip the switch off and on and the power should be back on, provided the hardware hack for V1.0 is installed (see :ref:`Bodge Switch`). - -TTL or RS485 and biasing -======================== - -R1-R4 and R9-R12 are used to bias the differential lines of the RS485 signal such that when no transceiver is active, -no garbage gets transmitted over the bus. These components should always be populated. - -The RS485 transceivers can also speak TTL if the board is configured correctly. -To achieve this R5-R8 need to be in place. This causes the B line of the RS485 signal to be held at 2.5V. -The A line of the RS485 signal will be the TTL signal. -The transceiver can interpret the incoming signal correctly since the voltage differential needs to be +0.2v for a 1 -and -0.2V for a 0. -If only RS485 is used, it is recommended to leave R5-R8 unpopulated. - -.. _Jumpers: - -Jumpers -======== - -Two jumpers exist on the Wolfgang CORE. - -P1: Enables the Teensy 4.0 to switch on and off the motor power. - -P2: Enables the power supply to the Teensy 4.0. **Do not use together with a USB cable plugged into the Teensy!!** - - - -Register Table -============== - -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| Adress | Length | Name | Access | Default | Type | Persistent? | -+========+========+=======================================+========+=========+=========+=============+ -| 7 | 1 | :ref:`id` | rw | 42 | int8 | yes | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 8 | 1 | :ref:`baud` | rw | 4 | int8 | yes | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 10 | 4 | :ref:`led0` | rw | 0 | int8[4] | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 14 | 4 | :ref:`led1` | rw | 0 | int8[4] | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 18 | 4 | :ref:`led2` | rw | 0 | int8[4] | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 22 | 1 | :ref:`teensy_led` | rw | 0 | int8 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 23 | 1 | :ref:`power_control` | rw | 1 | int8 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 28 | 2 | :ref:`VEXT` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 30 | 2 | :ref:`VCC` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 32 | 2 | :ref:`VDXL` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 34 | 2 | :ref:`current` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 36 | 2 | :ref:`manual_power_on` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 38 | 2 | :ref:`VBAT_0` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 40 | 2 | :ref:`VBAT_1` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 42 | 2 | :ref:`VBAT_2` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 44 | 2 | :ref:`VBAT_3` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 46 | 2 | :ref:`VBAT_4` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ -| 48 | 2 | :ref:`VBAT_5` | r | | int16 | no | -+--------+--------+---------------------------------------+--------+---------+---------+-------------+ - -.. _DXL_CORE: - -DXL ---- - -**id**: Can be a value between 1 and 252. It is used to talk to the device over the Dynamixel bus. - -**baud**: Can be a value between 0 and 7 - -+-------+---------+--------+ -| value | baud | Tested | -+=======+=========+========+ -| 0 | 9,600 | no | -+-------+---------+--------+ -| 1 | 57,600 | no | -+-------+---------+--------+ -| 2 | 115,200 | no | -+-------+---------+--------+ -| 3 | 1M | no | -+-------+---------+--------+ -| 4 | 2M | yes | -+-------+---------+--------+ -| 5 | 3M | no | -+-------+---------+--------+ -| 6 | 4M | yes | -+-------+---------+--------+ -| 7 | 4.5M | no | -+-------+---------+--------+ - -We are reasonably certain that the other baud rates work as well since the Teensy supports them. - - -.. _LEDs_CORE: - -LEDs ----- - -**led{0,1,2}**: Byte order: RGB, 4th byte is ignored but reserved. - - -.. _Power Control: - -Power Control -------------- - -**power_control**: Used to turn on and off the power (0 off, 1 on). Will be overwritten by manual switch if toggled. - -**manual_power_on**: Indicates whether the manual power switch is on. Requires :ref:`Bodge Switch` - -.. _Voltage Sensing: - -Voltage Sensing ---------------- - -Voltages are scaled down using a voltage divider to be read by the microcontroller. -Multiplying by the given scale factor returns the actual voltage on the voltage rail. -The scale factor is given as the conversion factor from analog reading to voltage multiplied by the factor of the voltage divider. -The factor of the voltage divider is given as (top_resistor/(top_resistor+bottom_resistor)). -It is recommended to use ±0.1% or ±1% resistors for the voltage dividers. - -**VEXT**: Raw reading of the external power supply voltage. Scale factor: (3.3 / 1024) * (2.0/(2.0+10.0)) - -**VCC**: Raw reading of the main voltage rail. Scale factor: (3.3 / 1024) * (2.0/(2.0+10.0)) - -**VDXL**: Raw reading of the voltage applied to the Dynamixel bus. Scale factor: (3.3 / 1024) * (2.0/(2.0+10.0)) - -**VBAT_{0..5}**: Raw reading of the voltage between ground and cell {0..5}. - -**VBAT_0**: Scale factor: (3.3 / 1024) * (3.3/(1.2+3.3)) - -**VBAT_1**: Scale factor: (3.3 / 1024) * (3.6/(6.2+3.6)) - -**VBAT_2**: Scale factor: (3.3 / 1024) * (2.2/(6.8+2.2)) - -**VBAT_3**: Scale factor: (3.3 / 1024) * (3.6/(16.0+3.6)) - -**VBAT_4**: Scale factor: (3.3 / 1024) * (6.2/(36.0+6.2)) - -**VBAT_5**: Scale factor: (3.3 / 1024) * (1.8/(13.0+1.8)) - - -.. _Current Sensing: - -Current Sensing ---------------- - -Current is sensed using a Hall effect sensor (ACS712ELCTR-30A-T to be exact). -It has to be scaled by the conversion factor from analog reading to voltage multiplied by the amperes per volt to get the actual current. -Furthermore, the reading is offset by 2.5V since the sensor can measure positive and negative currents. - -**current**: Raw reading of the current sensor. Scale factor: (3.3 / 1024)) - 2.5) / -0.066 diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/motorcable.rst b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/motorcable.rst deleted file mode 100644 index 585b0e2211..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/motorcable.rst +++ /dev/null @@ -1,45 +0,0 @@ -============ -Motor Cables -============ - -The cables of the Wolfgang robot are color coded by length. -At some positions (Elbow, Hip, Knee, Ankle) the cables are fixed on the motor horns using *Kabeldinger*. -Those are 3D printed. -The files for this are in our Onshape repository and also in the bitsbots_hardware git. - -Colors ------- - -* **Blue**: 45cm -* **Green**: 32cm -* **Gray**: 24cm -* **Yellow**: 20cm -* **White**: 10cm - -Amounts for a single robot ---------------------------- - -* **Blue**: 4 pc. -* **Green**: 5 pc. -* **Gray**: 4 pc. -* **Yellow**: 4 pc. -* **White**: 6 pc. - -Positions of the Cables ------------------------ - -* Head Yaw -> Head Pitch: Yellow -* Power -> Head Yaw: Yellow -* Power -> L. Arm: Yellow -* Power -> R. Arm: Gray -* Shoulders: Green -* Upper Arm: Green -* DXL -> Distributor: White -* Power -> Distributor: Yellow -* Distributor -> L. Leg: Green -* Distributor -> R. Leg: Gray -* Hip: Gray -* Upper Leg: Blue -* Lower Leg: Blue -* Motorcombi (Connection of the two motors on the hip and ankle): White -* Ankle -> Foot: White/Yellow 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 deleted file mode 100644 index 7e3fe099de..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/screws.rst +++ /dev/null @@ -1,116 +0,0 @@ -====== -Screws -====== - -Wolfgang -======== - -**NOTE: This is outdated and lacks some screws that were added later. Use with caution.** - -By Position ------------ - -+----------------------------------------+----------+--------+------------+ -| Position | Type | Amount | Per Robot | -| | | | | -+----------------------------------------+----------+--------+------------+ -| Camera holder | M2,5x12 | 4 | 1 | -+----------------------------------------+----------+--------+------------+ -| Head -> HeadTilt | M2,5x8 | 10 | 1 | -+----------------------------------------+----------+--------+------------+ -| HeadTilt -> HeadPan | M2,5x6 | 4 | 1 | -+----------------------------------------+----------+--------+------------+ -| HeadPan -> Torso | M2,5x8 | 8 | 1 | -+----------------------------------------+----------+--------+------------+ -| Protectors Torso | M2,5x8 | 3 | 4 | -+----------------------------------------+----------+--------+------------+ -| L/RShoulderPitch -> Torso | M2,5x8 | 8 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RShoulderPitch -> Shoulder | M2,5x4 | 8 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RShoulderRoll -> Shoulder | M2,5x4 | 5 | 2 | -+----------------------------------------+----------+--------+------------+ -| Shoulder Protector | M2,5x8 | 6 | 2 | -+----------------------------------------+----------+--------+------------+ -| Shoulder Protector -> L/RShoulderRoll | M2,5x5 | 4 | 2 | -+----------------------------------------+----------+--------+------------+ -| Shoulder Protector -> Shoulder | M2,5x8 | 5 | 2 | -+----------------------------------------+----------+--------+------------+ -| ShoulderRoll -> Upper Arm (Front/Back) | M2,5x8 | 8 | 2 | -+----------------------------------------+----------+--------+------------+ -| ShoulderRoll -> Upper Arm (on the side)| M2,5x6 | 16 | 2 | -+----------------------------------------+----------+--------+------------+ -| Upper Arm stabilizer | M2,5x8 | 4 | 4 | -+----------------------------------------+----------+--------+------------+ -| L/RElbow -> Upper Arm | M2,5x4 | 16 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RElbow -> Lower Arm | M2,5x8 | 12 | 2 | -+----------------------------------------+----------+--------+------------+ -| Hand Stabilizer | M2,5x8 | 10 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RHipYaw -> Torso | M2,5x8 | 8 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RHipYaw -> Hip Joint | M2,5x6 | 8 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RHipRoll -> L/RHipPitch (front) | M2,5x6 | 4 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RHipRoll -> L/RHipPitch (side) | M2,5x8 | 4 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RHipRoll+Pitch -> Hip Joint (F./B.) | M2,5x4 | 14 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RHipPitch -> Hip Joint (side) | M2,5x8 | 4 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RHipPitch -> Upper Leg | M2,5x4 | 16 | 2 | -+----------------------------------------+----------+--------+------------+ -| Upper Leg Stabilizer | M2,5x8 | 4 | 4 | -+----------------------------------------+----------+--------+------------+ -| L/RKnee -> Upper Leg (side) | M2,5x4 | 16 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RKnee -> Upper Leg (in the leg) | M2,5x6 | 8 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RKnee -> Lower Leg | M2,5x4 | 16 | 2 | -+----------------------------------------+----------+--------+------------+ -| Lower Leg Stabilizer (front) | M2,5x4 | 8 | 2 | -+----------------------------------------+----------+--------+------------+ -| Lower Leg Stabilizer (back) | M2,5x6 | 4 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RFootPitch -> Lower Leg | M2,5x4 | 16 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RFootPitch -> L/RFootRoll (inside) | M2,5x8 | 4 | 2 | -+----------------------------------------+----------+--------+------------+ -| L/RFootPitch -> L/RFootRoll(from back) | M2,5x6 | 4 | 2 | -+----------------------------------------+----------+--------+------------+ -| Feet Motors -> Foot Plate (front/back) | M2,5x4 | 14 | 2 | -+----------------------------------------+----------+--------+------------+ -| Feet Motors->Foot Plate(side of front) | M2,5x8 | 4 | 2 | -+----------------------------------------+----------+--------+------------+ -| Cleat (Ger: Stollen) | M2,5x10 | 1 | 8 | -+----------------------------------------+----------+--------+------------+ -| Stopper | M2,5x10 | 2 | 2 | -+----------------------------------------+----------+--------+------------+ -| Bearings | M3x8 | 1 | 35 | -+----------------------------------------+----------+--------+------------+ - - -By Count ------------ -+----------+---------+ -| Type | Amount | -| | | -+----------+---------+ -| M2,5x4 | 268 | -+----------+---------+ -| M2,5x6 | 100 | -+----------+---------+ -| M2,5x8 | 166 | -+----------+---------+ -| M2,5x10 | 12 | -+----------+---------+ -| M2,5x12 | 16 | -+----------+---------+ -| M3x8 | 35 | -+----------+---------+ - -Layout ------- -.. image:: screws/screws.jpg diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/screws/screws.jpg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/screws/screws.jpg deleted file mode 100644 index 23fe4d61e2..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/screws/screws.jpg and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/servo_numbers.rst b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/servo_numbers.rst deleted file mode 100644 index 39bd079e98..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/servo_numbers.rst +++ /dev/null @@ -1,5 +0,0 @@ -============= -Servo numbers -============= - -.. image:: servos/servo_numbers.png diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/servos/servo_numbers.png b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/servos/servo_numbers.png deleted file mode 100644 index b24666bdb2..0000000000 Binary files a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/servos/servo_numbers.png and /dev/null differ diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/servos/servo_numbers.svg b/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/servos/servo_numbers.svg deleted file mode 100644 index 418a7901db..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/hardware/mechanics/servos/servo_numbers.svg +++ /dev/null @@ -1,648 +0,0 @@ - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2 3 4 - 55 5 - - 6 - - - 7 - 8 - - 9 (back)11 (front) - - - 10 (back)12 (front) - 13 - - 14 - - - 15 (front)17 (back) 16 (front)18 (back) - 19 - - 20 - - - diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/competition_wifi.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/competition_wifi.rst similarity index 100% rename from src/bitbots_misc/bitbots_docs/docs/manual/tutorials/competition_wifi.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/competition_wifi.rst diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/configure_launch.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/configure_launch.rst new file mode 100644 index 0000000000..de0be3f0f8 --- /dev/null +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/configure_launch.rst @@ -0,0 +1,67 @@ +Configure & Launch a Robot +========================== + +This section describes how to configure and deploy your current software to a +robot for game preparation. + +.. note:: + See :doc:`starting_robot` for the prerequisites and safety warnings on when + it is safe to start the robot and how the software is synced and built. + +.. note:: + See :doc:`robots` for the robot names and IP addresses, and :doc:`setup_robot` + for the one-time Ansible provisioning of a robot. + +Deployment +---------- + +Deployment is the process of preparing a robot for the next game and starting the correct software. + +At a competition, follow these steps: + +#. **Configure Wi-Fi networks for fields:** + This needs to be done before the competition at the team area (see :doc:`competition_wifi`)! + +#. **Checkout the latest code:** + In your local `bitbots_main `_ repo run: + + #. Check that you are on the ``main`` branch + #. ``git pull`` to get the latest changes + +#. **Sync, configure, compile and launch software:** + In the ``bitbots_main`` directory run the deploy tool: + + .. code-block:: bash + + pixi run deploy + + 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) + - Build/Compile the source code you just synchronized to the robot(s) + - Launch the teamplayer software on the robot(s) + + If you need help with this tool, or want other options, look at `this README `_ for example usages or call: + + .. code-block:: bash + + pixi run deploy -h + +#. **Optional: Connect to the robot:** + Simply copy-paste the command provided by the deploy-tool when its finished. + See :doc:`connecting` for how to connect and how to use tmux. + +#. **Profit!** + The robot is now ready play! + +Cleanup +------- + +.. todo:: + Rework of the public documentation (see issue #1037): describe the cleanup + after a game/session: + + - Sit down the robot. + - Closing the tmux session. + - Copying and then deleting the recorded rosbag from the robot. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/connecting.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/connecting.rst new file mode 100644 index 0000000000..fc361b5a64 --- /dev/null +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/connecting.rst @@ -0,0 +1,13 @@ +Connecting to the Robot +======================= + +.. todo:: + Rework of the public documentation (see issue #1037): describe how to + connect to a running robot. It should cover: + + How to connect + How to connect to the robot (e.g. via SSH), reusing the connect command + that the deploy tool prints (see :doc:`configure_launch`). + + How to tmux + How to attach to and work inside the robot's tmux session. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/extrinsic_calibration.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/extrinsic_calibration.rst similarity index 97% rename from src/bitbots_misc/bitbots_docs/docs/manual/tutorials/extrinsic_calibration.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/extrinsic_calibration.rst index 2d664d354a..4f49872905 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/extrinsic_calibration.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/extrinsic_calibration.rst @@ -3,7 +3,7 @@ How to: Extrinsic Calibration ============================= | As robots frequently tumble and fall down, we need to adjust not correctly aligned parts of the robots in their calibration. | Additionally, we need the `Inverse Perspective Mapping (IPM) `_ -to map correctly camera pixels to field coordinates. +| to map correctly camera pixels to field coordinates. In order to adjust the calibration of the visualization you can change the roll (:code:`offset_x`), pitch (:code:`offset_y`) and yaw (:code:`offset_z`) of the camera and the IMU. The camera parameters change the camera direction and the IMU parameters change the orientation of the body. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/extrinsic_calibration/camera_coordinate_system.png b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/extrinsic_calibration/camera_coordinate_system.png similarity index 100% rename from src/bitbots_misc/bitbots_docs/docs/manual/tutorials/extrinsic_calibration/camera_coordinate_system.png rename to src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/extrinsic_calibration/camera_coordinate_system.png diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/extrinsic_calibration/right_handed_coordinate_system.png b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/extrinsic_calibration/right_handed_coordinate_system.png similarity index 100% rename from src/bitbots_misc/bitbots_docs/docs/manual/tutorials/extrinsic_calibration/right_handed_coordinate_system.png rename to src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/extrinsic_calibration/right_handed_coordinate_system.png diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/testing/competition_preparation.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/hardware_checklist.rst similarity index 83% rename from src/bitbots_misc/bitbots_docs/docs/manual/testing/competition_preparation.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/hardware_checklist.rst index d1d26a0226..8b956e30aa 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/testing/competition_preparation.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/hardware_checklist.rst @@ -1,6 +1,11 @@ Hardware Checklist (Pre-Competition) ==================================== +.. todo:: + Rework of the public documentation (see issue #1037): fully rework this + checklist for the PiPlus platform. Some items below refer to Wolfgang-specific + hardware (e.g. crimped motor cables, springs) and need to be revised. + When Powered Off ---------------- * Check cables for insulation damage @@ -47,7 +52,7 @@ After Powering On * Verify robot-specific walking parameters * Perform extrinsic calibration - Do the steps as described in `this documentation `_. + Do the steps as described in `this documentation `_. * Check camera images for focus and proper transmission (10 Hz, low jitter) Run: diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/lowlevel.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/lowlevel.rst new file mode 100644 index 0000000000..aecee78624 --- /dev/null +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/lowlevel.rst @@ -0,0 +1,21 @@ +Bitbots Lowlevel +================ + +.. todo:: + Rework of the public documentation (see issue #1037): this page previously + described the Wolfgang low level stack (Dynamixel motors on RS-485/TTL, the + CORE board, the Dynamixel SDK/Workbench and ``bitbots_ros_control``). None of + that applies to the PiPlus platform, which uses livelybot CAN-FD actuators + over a serial link. + + Rewrite this page to describe the PiPlus low level stack: + + - What the low level packages do and how the control loop is structured. + - The livelybot hardware SDK and serial protocol + (``src/lib/livelybot_hardware_sdk``) and how motors and the built-in IMU are + read and written. + - How the hardware interface integrates with ROS 2 control. + - Common problems and troubleshooting strategies. + + See :doc:`piplus_hardware` for the hardware overview and + :doc:`test_robot_hardware` for hardware/lowlevel testing. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/piplus_hardware.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/piplus_hardware.rst new file mode 100644 index 0000000000..5c31485cfc --- /dev/null +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/piplus_hardware.rst @@ -0,0 +1,30 @@ +PiPlus Hardware Overview +======================== + +This page gives an overview of the hardware of the PiPlus robot platform. + +.. todo:: + Rework of the public documentation (see issue #1037): write the PiPlus + hardware overview. It should replace the removed Wolfgang electronics and + mechanics pages and cover the following: + + Motors & Joints + Which motors and joints does the PiPlus have? Derive the joint names and + motor IDs from the livelybot serial configuration + (``src/lib/livelybot_hardware_sdk/src/livelybot_serial/config/robot.yaml``) + and the description package (``piplus_description``). This replaces the + former Wolfgang "servo numbers" reference. + + Computation devices + Which computation devices are on the robot (e.g. main computer, cameras)? + + Sensors + Which sensors are available (e.g. the IMU built into the livelybot serial + protocol, the camera)? + + Other outputs + Which other outputs exist? Document the built-in speaker and the LCD + display. This replaces the former standalone "Speaker" page. + + Ports + Which ports are there? Document the USB ports and which is which. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/robots.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/robots.rst new file mode 100644 index 0000000000..c95021015c --- /dev/null +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/robots.rst @@ -0,0 +1,54 @@ +List of Robots +============== + +We have multiple robots in our team, each with their own hostname and IP address. +Pi Plus Cameras do not use IP addresses, but are connected via USB. + +.. note:: + Current status as of May 2026 (Martyn does not exist yet): + ++----------+----------+-----------+-------------+ +| Name | Hostname | Username | IP | ++==========+==========+===========+=============+ +| Kalliope | kalliope | bitbots | 172.20.1.11 | ++----------+----------+-----------+-------------+ +| Mickey | mickey | bitbots | 172.20.1.12 | ++----------+----------+-----------+-------------+ +| Pink | pink | bitbots | 172.20.1.13 | ++----------+----------+-----------+-------------+ +| Romeo | romeo | bitbots | 172.20.1.14 | ++----------+----------+-----------+-------------+ +| Carrie | carrie | bitbots | 172.20.1.15 | ++----------+----------+-----------+-------------+ +| Peter | peter | bitbots | 172.20.1.16 | ++----------+----------+-----------+-------------+ +| Kiki | kiki | bitbots | 172.20.1.17 | ++----------+----------+-----------+-------------+ +| Martyn | martyn | bitbots | 172.20.1.18 | ++----------+----------+-----------+-------------+ + +Old Wolfgang robots + ++----------+----------+----------+-------------+-------------+ +| Name | Hostname | Username | IP | Camera IP | ++==========+==========+==========+=============+=============+ +| Amy | nuc1 | bitbots | 172.20.1.11 | 172.20.4.11 | ++----------+----------+----------+-------------+-------------+ +| Rory | nuc2 | bitbots | 172.20.1.12 | 172.20.4.12 | ++----------+----------+----------+-------------+-------------+ +| Jack | nuc3 | bitbots | 172.20.1.13 | 172.20.4.13 | ++----------+----------+----------+-------------+-------------+ +| Donna | nuc4 | bitbots | 172.20.1.14 | 172.20.4.14 | ++----------+----------+----------+-------------+-------------+ +| Melody | nuc5 | bitbots | 172.20.1.15 | 172.20.4.15 | ++----------+----------+----------+-------------+-------------+ +| Rose | nuc6 | bitbots | 172.20.1.16 | 172.20.4.16 | ++----------+----------+----------+-------------+-------------+ + +.. todo:: + Rework of the public documentation (see issue #1037): + + - Confirm the robot list is complete and up to date. + - If there is demand, add a copy-pastable ``/etc/hosts`` entry here (this + replaces the former "Configure hostnames" page, which was removed due to + low usage). diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/setup_robot.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/setup_robot.rst new file mode 100644 index 0000000000..ba99f8aa7d --- /dev/null +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/setup_robot.rst @@ -0,0 +1,44 @@ +Setting up a Robot +================== + +.. note:: + These Ansible setup steps configure a robot's operating system from scratch. + They are only relevant when provisioning a new robot or reinstalling one and + will not be useful for most users. If you only want to deploy and run the + software on an already configured robot, see :doc:`configure_launch`. + +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 +- 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 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:: + See :doc:`robots` for the robot names and IP addresses. diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/starting_robot.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/starting_robot.rst new file mode 100644 index 0000000000..b08602fa86 --- /dev/null +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/starting_robot.rst @@ -0,0 +1,17 @@ +Starting the Robot +================== + +.. todo:: + Rework of the public documentation (see issue #1037): describe how to start + a physical robot. It should cover: + + How to power on + The steps to power on the robot. + + Motor power safety + Only enable motor power when the joints are in a normal position (note and photo of T-pose AND markers to identify normal position) and no + motion is running. + + Deploy tool sync & build + How to sync and build the software onto the robot with the deploy tool + (see :doc:`configure_launch` for the full deploy & launch flow). diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_robot_hardware.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/test_robot_hardware.rst similarity index 92% rename from src/bitbots_misc/bitbots_docs/docs/manual/testing/test_robot_hardware.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/test_robot_hardware.rst index fa19d077f3..612525498a 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_robot_hardware.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/test_robot_hardware.rst @@ -2,6 +2,11 @@ Testing the robot hardware and lowlevel software ================================================ +.. todo:: + Rework of the public documentation (see issue #1037): fully rework this page + for the PiPlus platform. The current steps assume the Wolfgang low level stack + and need to be revised for the livelybot hardware. + Do the test in the provided order, to find out which part is faulty. Preliminaries diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_motion.rst b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/testing_robot.rst similarity index 63% rename from src/bitbots_misc/bitbots_docs/docs/manual/testing/test_motion.rst rename to src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/testing_robot.rst index 4b67922ae0..9b9ec1e7da 100644 --- a/src/bitbots_misc/bitbots_docs/docs/manual/testing/test_motion.rst +++ b/src/bitbots_misc/bitbots_docs/docs/manual/physical_robot/testing_robot.rst @@ -1,6 +1,18 @@ -======================== -Testing the robot motion -======================== +================= +Testing the Robot +================= + +.. todo:: + Rework of the public documentation (see issue #1037): expand this page to + cover all robot testing. It should: + + - Reference :doc:`starting_robot` (and :doc:`configure_launch`) for the + warnings on when it is *not* safe to start the robot. + - Describe starting motion standalone (see below). + - Replace the ``# TODO Start RL motions`` placeholders with the actual RL + motion commands (see :doc:`../development/rl_models`). + - Describe starting teleop. + - Link to :doc:`extrinsic_calibration` for the extrinsic calibration. Make sure to test in order, since there are dependencies between some things. 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 deleted file mode 100644 index 6cb0a87be9..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/configure_and_flash_robot.rst +++ /dev/null @@ -1,136 +0,0 @@ -Configure and Deploy to a robot -=============================== - -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. -Pi Plus Cameras do not use IP addresses, but are connected via USB. - -.. note:: - Current status as of May 2026: - -+----------+----------+-----------+-------------+ -| Name | Hostname | Username | IP | -+==========+==========+===========+=============+ -| Kalliope | kalliope | bitbots | 172.20.1.11 | -+----------+----------+-----------+-------------+ -| Mickey | mickey | bitbots | 172.20.1.12 | -+----------+----------+-----------+-------------+ -| Pink | pink | bitbots | 172.20.1.13 | -+----------+----------+-----------+-------------+ -| Romeo | romeo | bitbots | 172.20.1.14 | -+----------+----------+-----------+-------------+ -| Carrie | carrie | bitbots | 172.20.1.15 | -+----------+----------+-----------+-------------+ -| Peter | peter | bitbots | 172.20.1.16 | -+----------+----------+-----------+-------------+ -| Kiki | kiki | bitbots | 172.20.1.17 | -+----------+----------+-----------+-------------+ -| Martyn | martyn | bitbots | 172.20.1.18 | -+----------+----------+-----------+-------------+ - -Old robots - -+----------+----------+----------+-------------+-------------+ -| Name | Hostname | Username | IP | Camera IP | -+==========+==========+==========+=============+=============+ -| Amy | nuc1 | bitbots | 172.20.1.11 | 172.20.4.11 | -+----------+----------+----------+-------------+-------------+ -| Rory | nuc2 | bitbots | 172.20.1.12 | 172.20.4.12 | -+----------+----------+----------+-------------+-------------+ -| Jack | nuc3 | bitbots | 172.20.1.13 | 172.20.4.13 | -+----------+----------+----------+-------------+-------------+ -| Donna | nuc4 | bitbots | 172.20.1.14 | 172.20.4.14 | -+----------+----------+----------+-------------+-------------+ -| Melody | nuc5 | bitbots | 172.20.1.15 | 172.20.4.15 | -+----------+----------+----------+-------------+-------------+ -| Rose | nuc6 | bitbots | 172.20.1.16 | 172.20.4.16 | -+----------+----------+----------+-------------+-------------+ - -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 -- 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 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 ``hostname``? 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:** - This needs to be done before the competition at the team area (see :doc:`competition_wifi`)! - -#. **Checkout the latest code:** - In your local `bitbots_main `_ repo run: - - #. Check that you are on the ``main`` branch - #. ``git pull`` to get the latest changes - -#. **Sync, configure, compile and launch software:** - In the ``bitbots_main`` directory run the deploy tool: - - .. code-block:: bash - - pixi run deploy - - 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) - - Build/Compile the source code you just synchronized to the robot(s) - - Launch the teamplayer software on the robot(s) - - If you need help with this tool, or want other options, look at `this README `_ for example usages or call: - - .. code-block:: bash - - pixi run deploy -h - -#. **Optional: Connect to the robot:** - Simply copy-paste the command provided by the deploy-tool when its finished. - -#. **CURRENTLY DISABLED: Reset foot pressure sensors:** - Pick up the robot, so that the feet do not touch the ground. - Long press the green button on the IMU, which resets the foot pressure sensors. - -#. **Profit!** - The robot is now ready play! diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/configure_hostnames.rst b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/configure_hostnames.rst deleted file mode 100644 index edc476eff7..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/configure_hostnames.rst +++ /dev/null @@ -1,15 +0,0 @@ -Configure host names --------------------- - -This is helpful, if you don't want to always type out the full IP address of our robots when no DNS server is available (e.g. at a competition). - -Append the following lines to your ``/etc/hosts`` file: - -.. code:: bash - - 172.20.1.11 nuc1 amy - 172.20.1.12 nuc2 rory - 172.20.1.13 nuc3 jack - 172.20.1.14 nuc4 donna - 172.20.1.15 nuc5 melody - 172.20.1.16 nuc6 rose diff --git a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/lowlevel.rst b/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/lowlevel.rst deleted file mode 100644 index 6bc2b63810..0000000000 --- a/src/bitbots_misc/bitbots_docs/docs/manual/tutorials/lowlevel.rst +++ /dev/null @@ -1,191 +0,0 @@ -Bitbots Lowlevel -================ - -What do the low level packages do? ----------------------------------- - -The low level packages are responsible for the robot's motion. -The different hardware and software components used are described in this article. -Additionally, common problems and troubleshooting strategies are explained. - -The behavior of the low level packages is dominated by the control loop, i.e. the cycle that alternately reads and writes motor positions. -In parallel to this cycle, the new positions are calculated based on observed values. - -To react to problems as fast as possible, e.g. overload errors in the motors, a faster control loop is desirable. -Formerly, our loop ran with a frequency of 100Hz, therefore the reaction time to errors is at least 20ms because the error has to be read, processed and written, which takes at least two cycles. - -There are essentially three possibilities to accelerate the control loop: - -1. Send the bits faster over the bus, but this is limited by the baud rate of up to four megabaud (Robotis claims to achieve 4.5 MBaud, but we were not able to reproduce this) -2. Compress the data, e.g. by using special commands to read multiple motors at once (sync read and sync write) -3. Use more buses, in our case, one bus per limb would make sense - -Since we cannot increase the baud rate due to these limitations, our code only utilizes the second and third points. - -How is the hardware control structured? ---------------------------------------- - -Motors and Buses -~~~~~~~~~~~~~~~~ - -The lowest end of the hardware control are the motors. -We use Dynamixel motors MX-106 and MX-64, as well as the XH540 by Robotis. -The motors are connected by the motorbus using RS-485 or TTL. - -The cables for RS-485 consist of four wires, two of which are ground and VCC (14.8 to 16.8 V, depending on the current battery voltage), one for data (5V) and one for the inverted data. -When crimping new cables or when connecting a logic analyzer, it is important to not interchange the data and VCC cables because the motors are damaged when there are more than 5V on the data bus. - -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. - When crimping new cables, it is important to follow this scheme. - -The communication with the motors happens via the Dynamixel Bus Protocol. -Details are documented in their protocol specification. -We are using protocol `Version 2 -`_, but protocol `Version 1 -`_ can be used as a reference as well. - -A message of the protocol essentially consists of a header, the goal motor id, an instruction, a parameter list and a check sum. -The most important instructions are ping, read, write and status as well as sync read and sync write to read/write multiple motors at once. - -Every motor has a fixed id by which it can be addressed. -The id of a new / reset motor is 1 but can be changed using a write instruction to a special register. We can do this for example using the `dynamixel wizard `_. -A reference to the ids we use in our robot can be found here: :doc:`../hardware/mechanics/servo_numbers` - -Two motors with the same id should not be connected to the same bus because of the resulting communication problems. - -On a sync read, the motors answer in the order by which they are addressed in the sync read. -When one of the motors does not answer, the following motors will also not answer because they wait for the previous motor. - -CORE Board -~~~~~~~~~~ - -The CORE Board is connected to the NUC via USB and to the motors via the four motor busses. -It takes care of the communication between the NUC and the motors by reading message from the bus and redirecting them to the NUC and vice versa. -The IMU is also located on the bus and its values are treated the same as the motor values. - -Kernel -~~~~~~ -You should adjust the latency timer value. For the version Ubuntu 16.04.2 and later, the default latency timer of the usb serial is '16 msec'. When you are going to use sync / bulk read, the latency timer should be loosen. The lower latency timer value, the faster communication speed. - -You can check its value by: - - -.. code:: bash - - $ cat /sys/bus/usb-serial/devices/ttyUSB0/latency_timer - -If you think that the communication is too slow, type the following after plugging the usb in to change the latency timer - -Method 1. Type the following (you should do this everytime when the usb was plugged out or the connection was dropped) - -.. code:: bash - - $ echo 1 | sudo tee /sys/bus/usb-serial/devices/ttyUSB0/latency_timer - $ cat /sys/bus/usb-serial/devices/ttyUSB0/latency_timer - -Method 2. If you want to set it to be done automatically, and don't want to do the above everytime, make rules file in /etc/udev/rules.d/. For example, - -.. code:: bash - - $ echo ACTION==\"add\", SUBSYSTEM==\"usb-serial\", DRIVER==\"ftdi_sio\", ATTR{latency_timer}=\"1\" > 99-dynamixelsdk-usb.rules - $ sudo cp ./99-dynamixelsdk-usb.rules /etc/udev/rules.d/ - $ sudo udevadm control --reload-rules - $ sudo udevadm trigger --action=add - $ cat /sys/bus/usb-serial/devices/ttyUSB0/latency_timer - -If you have another good idea that can be an alternative, Robotis is asking for advice via a Github issue: https://github.com/ROBOTIS-GIT/DynamixelSDK/issues - - -Dynamixel SDK -~~~~~~~~~~~~~ - -The Dynamixel SDK implements the Dynamixel protocol. -It provides methods to send instructions and to read status packets in different programming languages. -We use a `fork `_ of Robotis' Dynamixel SDK because Robotis did not implement the sync read on multiple registers. - -Dynamixel Workbench -~~~~~~~~~~~~~~~~~~~ - -The Dynamixel Workbench provides higher level functions than the Dynamixel SDK. -For example, the motor positions in the SDK are given as values between 0 and 4096 (2 Byte) which is converted to radians by the Dynamixel Workbench. -Thereby, the Workbench eases the work with the motors on a more abstract level. -We use `a fork `_ which specifies our custom devices. - -ROS Control Framework -~~~~~~~~~~~~~~~~~~~~~ - -The ROS Control Framework is a part of ROS that is responsible for the motor and sensor control. -There are controllers for ROS Control that provide the interface between ROS and low level software parts. -These controllers are hardware agnostic because they are using interfaces to abstract from the hardware (e.g. motors). -To control the motors, the Dynamixel Controller is used, which itself uses the Dynamixel Hardware Interface. - -ROS messages -~~~~~~~~~~~~ - -After all these steps we're finally at the ROS message level. -There are two message types handled here: The joint state message gives the current positions of the motors, while the joint goals message can specify target positions for motors. The hardware interface also manages the IMU data and the values returned by the foot sensors. - -How do we use bitbots_ros_control? ----------------------------------- - -The package bitbots_ros_control provides the hardware interface for the dynamixel motors. - -The most important configuration file for this is the wolfgang.yaml. In this file you find multiple settings for defining, which values should be read from the motors (temperature, speed, force, ...), which sensors should be used (foot pressure sensors, IMU) and which settings should be set (control loop frequency, baud rate, CORE ports, auto torque, ...). - -The corresponding ROS node can be launched with `roslaunch bitbots_ros_control ros_control.launch`. This will execute the following steps: - -1. The motors are pinged in alphabetical order. This happens due to the way yaml files are read. This means the HeadPan motor (id 19) is read first, while the RShoulderRoll motor (id 3) is read last. -2. The values from the config file are written into the RAM and ROM of the motors. These are values like speed or return delay time. -3. The message "Hardware interface init finished" is printed to the terminal. -4. The control loop starts, alternating between sync read and sync write. -5. The controllers for ROS control are loaded. - -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 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. -If the names are different, you may have to alter the wolfgang.yaml file or unplug the CORE board and plug it back in, in order to make it use the known names. - -Motor problems -~~~~~~~~~~~~~~ - -The first thing you should do if you have a motor problem ("no status from id", motors stuttering, ...) is checking whether all cables are plugged in correctly, starting with the cables that are near the affected motor. -Sometimes one of the cable sits loosely in its socket and may fall out entirely when the robot moves. -To control whether all motors are reachable, this `software -by Robotis `_ can be used. -Next you should check whether the update rate is significantly lower than the usual 700 Hz. -A very low update rate may cause the motors to be unreachable. - -If the problem persists, you can investigate it further by using a logic analyzer to find bus errors. -The logic analyzer is a little black box with a lot of coloured wires ( `like this `_). -With this tool you can read the data from up to 16 busses at a time. -To do so, plug the ground cable into the ground of the bus and one of the coloured cables into one of the data wires. -It is very important not to confuse these two cables, as this may cause serious damage to the motors or the analyzer. - -By using the software Saleae Logic, the data can be recorded and read. -To do so, you have to select 15MB/s and a voltage of 5V via the button next to the start button. -Next you can start the recording and then start the problematic program. Now the Async Serial Analyzer can be used to show the bytes of the messages, which can be decoded using the protocols linked above, or install the dynamixel analyzer plugin provided `here