From 9953ace305f28030276899efb968eea84415a1fd Mon Sep 17 00:00:00 2001 From: Wolfgang Hoenig Date: Mon, 16 Oct 2023 21:14:10 +0200 Subject: [PATCH] Docs: update and move topics * Update the current state * Move advanced topics to HowTo --- docs2/howto.rst | 44 +++++++++++++++++++++++++++++++++ docs2/index.rst | 35 -------------------------- docs2/overview.rst | 13 +++++----- docs2/usage.rst | 61 +++++----------------------------------------- 4 files changed, 57 insertions(+), 96 deletions(-) diff --git a/docs2/howto.rst b/docs2/howto.rst index f51406141..abdeecc1c 100644 --- a/docs2/howto.rst +++ b/docs2/howto.rst @@ -47,3 +47,47 @@ If you don't have xterm installed, you can do so using `sudo apt install xterm`. colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Debug ros2 launch crazyflie launch.py debug:=True +Usage from the command line +--------------------------- + +The following shows a simple take off and land example + +.. code-block:: bash + + [terminal1]$ ros2 run crazyflie reboot --uri radio://0/80/2M/E7E7E7E706 --mode sysoff + [terminal2]$ ros2 launch crazyflie launch.py + [terminal1]$ ros2 param set crazyflie_server cf1.params.commander.enHighLevel 1 + [terminal1]$ ros2 param set crazyflie_server cf1.params.stabilizer.estimator 2 + [terminal1]$ ros2 service call cf1/takeoff crazyflie_interfaces/srv/Takeoff "{height: 0.5, duration: {sec: 2}}" + [terminal1]$ ros2 service call cf1/land crazyflie_interfaces/srv/Land "{height: 0.0, duration: {sec: 2}}" + +Enabling Logblocks at runtime +----------------------------- + +.. warning:: + Runtime logblock enabling is currently only supported in the CFLIB backend of the server. + +In the usage we explained how to enable log blocks at startup, but what if you would like to enable or disable logging blocks in runtime? +This section will show how to do that by using services + +In one terminal run + +.. code-block:: bash + + ros2 launch crazyflie launch.py backend:=cflib + +In another terminal after sourcing the right setup.bash files, run: + +.. code-block:: bash + + ros2 service call /cf2/add_logging crazyflie_interfaces/srv/AddLogging "{topic_name: 'topic_test', frequency: 10, vars: ['stateEstimate.x','stateEstimate.y','stateEstimate.z']}" + ros2 service call /cf2/add_logging crazyflie_interfaces/srv/AddLogging "{topic_name: 'pose', frequency: 10}" + +With ROS 2's rqt you can look at the topics, or with 'ROS 2 topics echo /cf2/pose' + +To close the logblocks again, run: + +.. code-block:: bash + + ros2 service call /cf2/remove_logging crazyflie_interfaces/srv/RemoveLogging "{topic_name: 'topic_test'}" + ros2 service call /cf2/remove_logging crazyflie_interfaces/srv/RemoveLogging "{topic_name: 'pose'}" \ No newline at end of file diff --git a/docs2/index.rst b/docs2/index.rst index f12766bdd..9e1557fe1 100644 --- a/docs2/index.rst +++ b/docs2/index.rst @@ -12,44 +12,9 @@ Crazyswarm2 is primarily made for researchers that want to operate or simulate a .. warning:: Crazyswarm2 is already usable for basic tasks (teleoperation, flying in a motion capture space, data collection), however the API and configuration file formats might still change. While many features of Crazyswarm1 are ported, there are currently still some important limitations: - - Limited support for real-time logging (logging on uSD-card is supported) - Tested only for small team sizes (less than 10 robots) - Limited Python API and only a few example scripts - - - -.. Both can be used to control several Crazyflies from a Python script. -.. Here are some differences: - -.. - **Motion capture integration.** -.. Crazyswarm contains drivers for common motion capture systems. -.. The Bitcraze API can *send* position measurements to the Crazyflie, -.. but does not know how to *get* position measurements from mocap hardware. -.. - **Identical or single motion capture markers.** -.. Via `libobjecttracker `_, -.. Crazyswarm can track multiple quadrotors with identical motion capture marker arrangements, -.. or quadrotors with only one marker each. -.. Most motion capture devices do not support this natively. -.. To make it possible, the user must supply the quadrotors' initial positions in a configuration file -.. at startup to establish the mapping from radio addresses to positions. -.. - **Broadcasts.** -.. Crazyswarm uses broadcast communication whenever possible to require fewer radios per Crazyflie. In contrast, the official SDK uses unicast communication instead. -.. - **Simulation.** -.. Crazyswarm has a simulation mode with 3D graphics, -.. which makes it easy to validate complex scripts before running them on real hardware. -.. - **Python firmware bindings.** -.. Crazyswarm's simulator is built upon automatically generated Python bindings -.. for certain modules in the Crazyflie firmware. -.. The binding system can be helpful when developing new firmware modules, -.. especially when they are mathematically complex and hard to debug. -.. - **ROS foundation.** -.. The Crazyswarm server program is a ROS node. -.. The :ref:`api` is a thin wrapper around the ROS interface. -.. While we recommend the Python API for most applications, -.. the ROS interface is fully supported. - - .. Crazyswarm's academic origins .. ----------------------------- diff --git a/docs2/overview.rst b/docs2/overview.rst index 12765ae60..7383949ee 100644 --- a/docs2/overview.rst +++ b/docs2/overview.rst @@ -8,8 +8,8 @@ This page will explain the overview of the crazyflie ROS 2 nodes: .. image:: images/overview_nodes.jpg -Explanation per node --------------------- +Explanation per package +----------------------- In the `source code of the Crazyswarm2 (Crazyflie ROS 2) project `_, there are several packages that we will explain here: @@ -17,17 +17,19 @@ In the `source code of the Crazyswarm2 (Crazyflie ROS 2) project `_ with on or more `Crazyradio PA dongles `_. -It has two backends that you can choose from: +It has three backends that you can choose from: - **cpp**: This is based on the `crazyflie-link-cpp `_ on the lowest layer. - **cflib**: This is based on the `crazyflie-lib-python `_ up until the logging, parameter, and command sending handling. +- **sim**: Our simulator behaves like a regular backend, offering ROS 2 topics and services, see below for more details on the simulation. It handles several low level communication aspects with the Crazyflies: @@ -47,8 +49,7 @@ Simulation The simulator uses the Crazyflie firmware as a software-in-the-loop (SIL). It provides the same ROS interface as the server and therefore can be used with C++ or Python user code. -Currently, the desired setpoint is visualized in rviz (see :ref:`usage`). However, the code is prepared to support physics-based simulation in the future as well. - +Currently, the desired setpoint is visualized in rviz (see :ref:`usage`) or a simple physics-based simulator can be used. Support functionality with backends ----------------------------------- diff --git a/docs2/usage.rst b/docs2/usage.rst index 0ab9246db..c35939ff7 100644 --- a/docs2/usage.rst +++ b/docs2/usage.rst @@ -124,57 +124,12 @@ Example: .. code-block:: bash - ros2 launch crazyflie launch.py backend:=sim - ros2 run crazyflie_examples hello_world --ros-args -p use_sim_time:=True + [terminal1]$ ros2 launch crazyflie launch.py backend:=sim + [terminal2]$ ros2 run crazyflie_examples hello_world --ros-args -p use_sim_time:=True Physical Experiments -------------------- -ROS 2 terminal -~~~~~~~~~~~~~~ - -The following shows a simple take off and land example without any launch files or yaml files - -.. code-block:: bash - - ros2 run crazyflie reboot --uri radio://0/80/2M/E7E7E7E706 --mode sysoff - ros2 param set crazyflie_server cf1.params.commander.enHighLevel 1 - ros2 param set crazyflie_server cf1.params.stabilizer.estimator 2 - ros2 service call cf1/takeoff crazyflie_interfaces/srv/Takeoff "{height: 0.5, duration: {sec: 2}}" - ros2 service call cf1/land crazyflie_interfaces/srv/Land "{height: 0.0, duration: {sec: 2}}" - -Enabling Logblocks at runtime -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. warning:: - Runtime logblock enabling is currently only supported in the CFLIB backend of the server. - -Above we explained how to enable log blocks at startup, but what if you would like to enable or disable logging blocks in runtime? -This section will show how to do that by using services - -In one terminal run - -.. code-block:: bash - - ros2 launch crazyflie launch.py backend:=cflib - -In another terminal after sourcing the right setup.bash files, run: - -.. code-block:: bash - - ros2 service call /cf2/add_logging crazyflie_interfaces/srv/AddLogging "{topic_name: 'topic_test', frequency: 10, vars: ['stateEstimate.x','stateEstimate.y','stateEstimate.z']}" - ros2 service call /cf2/add_logging crazyflie_interfaces/srv/AddLogging "{topic_name: 'pose', frequency: 10}" - -With ROS 2's rqt you can look at the topics, or with 'ROS 2 topics echo /cf2/pose' - -To close the logblocks again, run: - -.. code-block:: bash - - ros2 service call /cf2/remove_logging crazyflie_interfaces/srv/RemoveLogging "{topic_name: 'topic_test'}" - ros2 service call /cf2/remove_logging crazyflie_interfaces/srv/RemoveLogging "{topic_name: 'pose'}" - - Teleoperation controller ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -188,14 +143,10 @@ We currently assume an XBox controller (the button mapping can be changed in tel Python scripts ~~~~~~~~~~~~~~ -In the first terminal, launch - -.. code-block:: bash - - ros2 launch crazyflie launch.py - -In the second terminal +In the first terminal run the server, in the second the desired script. +You may run the script multiple times or different scripts while leaving the server running. .. code-block:: bash - ros2 run crazyflie_examples hello_world + [terminal1]$ ros2 launch crazyflie launch.py + [terminal2]$ ros2 run crazyflie_examples hello_world