Skip to content

Commit

Permalink
Merge pull request #511 from IMRCLab/add-positioning-doc
Browse files Browse the repository at this point in the history
Add positioning doc
  • Loading branch information
knmcguire authored May 31, 2024
2 parents 1a78766 + 796c5b5 commit 8ac5b7f
Show file tree
Hide file tree
Showing 3 changed files with 77 additions and 12 deletions.
4 changes: 2 additions & 2 deletions crazyflie/config/motion_capture.yaml
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
/motion_capture_tracking:
ros__parameters:
# one of "optitrack", "optitrack_closed_source", "vicon", "qualisys", "nokov", "vrpn", "motionanalysis"
type: "optitrack"
# Specify the hostname or IP of the computer running the motion capture software
hostname: "141.23.110.143"

mode: "libobjecttracker" # one of motionCapture,libRigidBodyTracker

topics:
poses:
qos:
Expand Down
5 changes: 3 additions & 2 deletions crazyflie/launch/launch.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
from launch.actions import DeclareLaunchArgument
from launch_ros.actions import Node
from launch.conditions import LaunchConfigurationEquals
from launch.conditions import LaunchConfigurationNotEquals
from launch.conditions import IfCondition
from launch.substitutions import LaunchConfiguration, PythonExpression


Expand Down Expand Up @@ -83,13 +83,14 @@ def generate_launch_description():
DeclareLaunchArgument('debug', default_value='False'),
DeclareLaunchArgument('rviz', default_value='False'),
DeclareLaunchArgument('gui', default_value='True'),
DeclareLaunchArgument('mocap', default_value='True'),
DeclareLaunchArgument('server_yaml_file', default_value=''),
DeclareLaunchArgument('teleop_yaml_file', default_value=''),
DeclareLaunchArgument('mocap_yaml_file', default_value=''),
Node(
package='motion_capture_tracking',
executable='motion_capture_tracking_node',
condition=LaunchConfigurationNotEquals('backend','sim'),
condition=IfCondition(PythonExpression(["'", LaunchConfiguration('backend'), "' != 'sim' and '", LaunchConfiguration('mocap'), "' == 'True'"])),
name='motion_capture_tracking',
output='screen',
parameters= [PythonExpression(["'tmp_motion_capture.yaml' if '", LaunchConfiguration('mocap_yaml_file'), "' == '' else '", LaunchConfiguration('mocap_yaml_file'), "'"])],
Expand Down
80 changes: 72 additions & 8 deletions docs2/usage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ Usage
.. warning::
If you work in a shared network (lab, classroom) or similar, you might want to avoid
controlling other robots. This is in particular true for simulation. In this case,
If you work in a shared network (lab, classroom) or similar, you might want to avoid
controlling other robots. This is in particular true for simulation. In this case,
you can use

.. code-block:: bash
Expand All @@ -29,7 +29,7 @@ Usage
Configuration
-------------

All configuration files are in crazyflie/config.
All configuration files are in crazyflie/config.

* crazyflies.yaml : setting up everything related to the robots.
* server.yaml : setting up everything related to the server.
Expand All @@ -40,7 +40,7 @@ crazyflies.yaml
~~~~~~~~~~~~~~~

Each crazyflie should have an unique URI which can `be changed in Bitcraze's CFclient <https://www.bitcraze.io/documentation/repository/crazyflie-clients-python/master/userguides/userguide_client/#firmware-configuration/>`_.
They can also be enabled in case you don't want the server to connect with it.
They can also be enabled in case you don't want the server to connect with it.

.. code-block:: yaml
Expand Down Expand Up @@ -109,14 +109,78 @@ The yaml file also contain an 'all' field, in case you have parameters or loggin
estimator: 2 # 1: complementary, 2: kalman
controller: 2 # 1: PID, 2: mellinger
The above also contains an example of the firmware_logging field, where default topics can be enabled or custom topics based on the `existing log toc of the crazyflie <https://www.bitcraze.io/documentation/repository/crazyflie-firmware/master/api/logs//>`_.
Moreover, it also contains the firmware_params field, where parameters can be set at startup.
Also see the `parameter list of the crazyflie <https://www.bitcraze.io/documentation/repository/crazyflie-firmware/master/api/params//>`_ for that.
The above also contains an example of the firmware_logging field, where default topics can be enabled or custom topics based on the `existing log toc of the crazyflie <https://www.bitcraze.io/documentation/repository/crazyflie-firmware/master/api/logs//>`_.
Moreover, it also contains the firmware_params field, where parameters can be set at startup.
Also see the `parameter list of the crazyflie <https://www.bitcraze.io/documentation/repository/crazyflie-firmware/master/api/params//>`_ for that.


Mind that you can also place the firmware_params and firmware_logging fields per crazyflie in 'robots' or the 'robot_types' field.
The server node will upon initialization, first look at the params/logs from the individual crazyflie's settings, then the robot_types, and then anything in 'all' which has lowest priority.
The server node will upon initialization, first look at the params/logs from the individual crazyflie's settings, then the robot_types, and then anything in 'all' which has lowest priority.

Positioning
-----------

The Crazyflie can be positioned in different ways, including motion capture and onboard positioning.
This blogpost provides a good overview of the different positioning systems if you are unsure about which one you are using: `Positioning System Overview <https://www.bitcraze.io/2021/05/positioning-system-overview/>`_.

Motion capture
~~~~~~~~~~~~~~

If you have a motion capture system, you can input the specifics in the motion_capture.yaml file.

.. code-block:: yaml
/motion_capture_tracking:
ros__parameters:
type: "optitrack"
hostname: "optitrackPC"
'Type' can replaced by "optitrack", "vicon", "qualisys" or any of the other supported motion capture systems of the `motion capture tracking package <https://github.com/IMRCLab/motion_capture_tracking/tree/ros2/>`_.
'hostname' is the hostname of the computer running the motion capture software which can either be the PC name or the IP.

Also make sure that in crazyflies.yaml, the motion_capture field is enabled for the specific robot type, or that the crazyflie is of a type that supports motion capture.

.. code-block:: yaml
robot_types:
cf21:
motion_capture:
enabled: true
For more indepth information about the motion capture tracking package, see the `documentation <https://github.com/IMRCLab/motion_capture_tracking/tree/ros2/>`_.

Onboard positioning
~~~~~~~~~~~~~~~~~~~

The Crazyflie also supports several alternative positioning systems that provide direct onboard position or pose estimation.
In this case you do not need to receive positioning from an external system like with MoCap.

Instructions per positioning system.:
* The `Loco positioning system <https://www.bitcraze.io/documentation/system/positioning/loco-positioning-system/>`_ - Follow Bitcraze's tutorial `here <https://www.bitcraze.io/documentation/tutorials/getting-started-with-loco-positioning-system/>`.
* The `Lighthouse positioning system <https://www.bitcraze.io/documentation/system/positioning/lighthouse/>`_ - Follow Bitcraze's tutorial `here <https://www.bitcraze.io/documentation/tutorials/getting-started-with-lighthouse-positioning-system/>`. Make sure to review the system management for saving and loading a system config, such that you don't have to redo the basestation geometry estimation for each crazyflie.
* The `Flow deck <https://www.bitcraze.io/products/flow-deck-v2/>`_ - Follow Bitcraze's tutorial `here <https://www.bitcraze.io/documentation/tutorials/getting-started-with-flow-deck/>`. Note that the flow deck provides an relative positoing estimate and might conflict when you are flying with crazyswarm2 if you are flying with absolute coordinates instead of relative ones.

Also in this case, make sure that motion_capture is disabled in the crazyflies.yaml file:

.. code-block:: yaml
robot_types:
cf21:
motion_capture:
enabled: false
Also it is a good idea to turn on pose estimation logging such that you are able to see the poses and transforms of the Crazyflie updated in real life in rviz or the Swarm management gui.

.. code-block:: yaml
firmware_logging:
enabled: true
default_topics:
pose:
frequency: 10 # Hz
Moreover, be aware that the motion capture node is enabled in the launch file by default, which can be turned off by adding 'mocap:=False' to the launch command.

Simulation
----------
Expand Down

0 comments on commit 8ac5b7f

Please sign in to comment.