Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: update and move topics #304

Merged
merged 1 commit into from
Oct 18, 2023
Merged

Docs: update and move topics #304

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs2/howto.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'}"
35 changes: 0 additions & 35 deletions docs2/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/USC-ACTLab/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
.. -----------------------------

Expand Down
13 changes: 7 additions & 6 deletions docs2/overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,26 +8,28 @@ 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 <https://github.com/IMRCLab/crazyswarm2>`_, there are several packages that we will explain here:


- **crazyflie/**: The package that contains the crazyflie server nodes and the crazyflies.yaml.
- **crazyflie_py/**: The package that contains the python library that wraps around the ROS 2 services and topics that connects with the crazyflie server nodes.
- **crazyflie_examples/**: The package that contains examples of using the crazyflie ROS 2 package. See :ref:`tutorials`.
- **crazyflie_interfaces/**: The package that contain all msgs and srvs for the crazyflie ROS 2 project.
- **crazyflie_interfaces/**: The package that contains all msgs and srvs for the crazyflie ROS 2 project.
- **crazyflie_sim/**: The package that contains our simulator.

Crazyflie server
----------------

The crazyflie server node connects multiple `Crazyflies <https://www.bitcraze.io/products/crazyflie-2-1/>`_ with on or more `Crazyradio PA dongles <https://www.bitcraze.io/products/crazyradio-pa/>`_.

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 <https://github.com/bitcraze/crazyflie-link-cpp>`_ on the lowest layer.
- **cflib**: This is based on the `crazyflie-lib-python <https://www.bitcraze.io/documentation/repository/crazyflie-lib-python/master/>`_ 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:

Expand All @@ -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
-----------------------------------
Expand Down
61 changes: 6 additions & 55 deletions docs2/usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -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
Loading