├── docs └── REEF_Architecture.jpg ├── .gitignore ├── .gitmodules ├── LICENSE └── README.md /docs/REEF_Architecture.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uf-reef-avl/reef_estimator_bundle/HEAD/docs/REEF_Architecture.jpg -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .idea/ 2 | cmake-build-debug/ 3 | # Prerequisites 4 | *.d 5 | 6 | # Compiled Object files 7 | *.slo 8 | *.lo 9 | *.o 10 | *.obj 11 | 12 | # Precompiled Headers 13 | *.gch 14 | *.pch 15 | 16 | # Compiled Dynamic libraries 17 | *.so 18 | *.dylib 19 | *.dll 20 | 21 | # Fortran module files 22 | *.mod 23 | *.smod 24 | 25 | # Compiled Static libraries 26 | *.lai 27 | *.la 28 | *.a 29 | *.lib 30 | 31 | # Executables 32 | *.exe 33 | *.out 34 | *.app 35 | *.swp 36 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "reef_control"] 2 | path = reef_control 3 | url = https://github.com/uf-reef-avl/reef_control 4 | [submodule "ros_astra_camera"] 5 | path = ros_astra_camera 6 | url = https://github.com/uf-reef-avl/ros_astra_camera 7 | [submodule "rosflight"] 8 | path = rosflight 9 | url = https://github.com/rosflight/rosflight 10 | [submodule "position_to_velocity"] 11 | path = position_to_velocity 12 | url = https://github.com/uf-reef-avl/position_to_velocity 13 | [submodule "reef_estimator"] 14 | path = reef_estimator 15 | url = https://github.com/uf-reef-avl/reef_estimator 16 | [submodule "reef_msgs"] 17 | path = reef_msgs 18 | url = https://github.com/uf-reef-avl/reef_msgs 19 | [submodule "reef_teleop"] 20 | path = reef_teleop 21 | url = https://github.com/uf-reef-avl/reef_teleop 22 | [submodule "rgbd_to_velocity"] 23 | path = rgbd_to_velocity 24 | url = https://github.com/uf-reef-avl/rgbd_to_velocity 25 | [submodule "ros_vrpn_client"] 26 | path = ros_vrpn_client 27 | url = https://github.com/uf-reef-avl/ros_vrpn_client 28 | [submodule "demo_rgbd"] 29 | path = demo_rgbd 30 | url = https://github.com/uf-reef-avl/demo_rgbd 31 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 University of Florida REEF Autonomous Vehicles Lab 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # REEF Estimator Bundle 2 | 3 | The REEF Estimator bundle is a collection of repositories that enable a quadrotor to fly holding altitude and take velocity commands from an XBox Controller (or similar controllers) in a indoor environment 4 | 5 | It consists the following packages 6 | - **REEF Estimator** - XY Velocity and Z estimators 7 | - **REEF Msgs** - Support package containing basic functions and ROS message declarations 8 | - **REEF Teleop** - Converts joy messages to desired commands for REEF control 9 | - **REEF Control** - Simple PID controllers for controlling the altitude and velocity of the vehicle 10 | - **Demo RGBD** - Algorithm to get odometry from RGBD images 11 | - **RGBD_to_velocity** - Converts the output of DEMO RGBD to velocity 12 | - **UNCC RGBD Odom** - RGBD algorithm to convert images to delta-pose estimatoes 13 | - **Position to Velocity** - Converts position to velocity 14 | - **Odom to Velocity** - Converts delta-pose to velocity 15 | - **ROS VRPN Client** - Interface between *Optitrack* (ONLY) and ROS. 16 | - **Astra Launch Driver** - Launch files to get the Orbbec Astra cameras to work 17 | - **Dubins Path** - Path planning algorithm to convert position to velocity requests 18 | 19 | 20 | ## If you use this work, please cite as: 21 | 22 | ```asm 23 | @inproceedings{ramos2019reef, 24 | title={REEF Estimator: A Simplified Open Source Estimator and Controller for Multirotors}, 25 | author={Ramos, J Humberto and Ganesh, Prashant and Warke, William and Volle, Kyle and Brink, Kevin}, 26 | booktitle={2019 IEEE National Aerospace and Electronics Conference (NAECON)}, 27 | pages={606--613}, 28 | year={2019}, 29 | organization={IEEE} 30 | } 31 | ``` 32 | 33 | ## Wiki 34 | Please read the [WIKI](https://github.com/uf-reef-avl/reef_estimator_bundle/wiki) for build instructions and additional documentation. 35 | 36 | ## Architecture 37 | 38 | The following image gives a high level overview of the design and how every package interacts with one another: 39 | 40 | ![REEF Est Architecture](./docs/REEF_Architecture.jpg) 41 | ## How do I get started? 42 | We have tested this bundle on multiple aerial platforms (quads and hexrotors) which had ROSFlight as their Flight Control Unit (FCU). The following instructions apply 43 | for ROSFlight only. If you do opt for other FCUs the estimator should work but you will have to work on the pipeline. The following steps will walk through the process of getting started from scratch i.e 44 | building a quadrotor platform to flying using an XBox Controller or flying figure 8 using motion capture. 45 | 46 | 1) Get a aerial robot or follow the [build instructions](https://github.com/uf-reef-avl/reef_estimator_bundle/wiki) to assemble a quadrotor. 47 | 2) Follow the [post build](https://github.com/uf-reef-avl/reef_estimator_bundle/wiki/Post-Build-RC-Configuration) configuration steps to get the quad ready to fly. 48 | 3) Clone and build the REEF_Estimator bundle onto the onboard computer: 49 | 50 | ```html 51 | mkdir -p reef_estimator_ws/src 52 | cd estimator_ws/src/ 53 | catkin_init_workspace 54 | git clone https://github.com/uf-reef-avl/reef_estimator_bundle 55 | cd reef_estimator_bundle 56 | git submodule update --init --recursive 57 | sudo apt install -y libuvc-dev ros-melodic-joy* libsuitesparse-dev libeigen3-dev libsdl1.2-dev 58 | cd ../.. && catkin build 59 | ``` 60 | **IMPORTANT: You may need to remove the joy package as it may not be found in ROS NOETIC**: If you have cloned the ROSFlight repo and the REEF Estimator bundle in estimator_ws/src, the compiler will throw an error when building. Delete the original ROSFlight package you built (not the one inside the bundle. This will save a tonne of time when pull new changes to the REEF Estimator code). 61 | 62 | 3) If you do have motion capture it is very important to perform a camera calibration. This involves both extrisic and intrisic calibration. Please 63 | take a look at our [camera calibration](https://bitbucket.org/reefavl/camear_calibration_bundle/src) package to do this. There is extensive documentation available in the [camera_mocap_calibration](https://bitbucket.org/reefavl/camera_mocap_calibration) package. 64 | 4) If you do not have motion capture measure the displacement between the IMU and the camera's optical frame along with the rotations. Convert the rotations to quaternions. 65 | 5) Take the output of Step 3 or Step 4 and enter them into the camera_to_body.yaml files in the following packages: 66 | - [REEF_Estimator](https://github.com/uf-reef-avl/reef_estimator/blob/master/params/dodo_camera.yaml) 67 | - [RGBD_to_Velocity](https://github.com/uf-reef-avl/rgbd_to_velocity/blob/master/params/kiwi_camera.yaml) 68 | - [Position_to_Velocity](https://github.com/uf-reef-avl/position_to_velocity/blob/master/params/camera_to_body.yaml) 69 | 6) After this step, we suggest you read the documentation in each of the packages in the bundle. Even if not EVERY package we highly recommend you go through these packages at least 70 | - [REEF_Estimator](https://github.com/uf-reef-avl/reef_estimator) 71 | - [REEF_Control](https://github.com/uf-reef-avl/reef_control) 72 | - [RGBD_to_Velocity](https://github.com/uf-reef-avl/rgbd_to_velocity) 73 | - [REEF_Teleop](https://github.com/uf-reef-avl/reef_teleop) 74 | 7) Once you've read through the documentation, we recommend that you get test the estimator while flying open-loop. The [record_raw.launch](https://bitbucket.org/reefavl/reef_estimator/src/master/launch/record_raw.launch) file will help record a bagfile with topics that is needed by the the estimator to run offline. 75 | 76 | **NOTE** This step assumes you have a mocap system. If you do not have one, just use the one's we've provided as a starting point. 77 | 78 | **NOTE** Clone and build the PlotJuggler package. This package will help you plot ROS Topics 79 | ```html 80 | cd catkin_ws/src 81 | sudo apt-get install qtbase5-dev libqt5svg5-dev ros-kinetic-ros-type-introspection ros-kinetic-plotjuggler 82 | cd .. 83 | catkin_make 84 | ``` 85 | 86 | 87 | 8) Once you have a tuned estimator, we can move on to the controller. The estimator is capable of taking reading from mocap or the sensors provided and we noticed the PID gains varies depending on the sensor. So, you can tune the gains depending on the sensors you plan on using. 88 | 9) We highly recommend that you focus on tuning the Z position and Z velocity controllers first before moving onto the other two axis. Use the dynamic tuning functionality to tune the controllers online 89 | 10) Once youre able to get decent params on the Z controllers, move onto the XY velocity controllers. 90 | **NOTE** You will be using the MIN_THROTTLE setting in the ROSFlight firmware to decide whether it gets commands from the RC or the computer. So, you will have to set the RC throttle to MAX. So it is highly advisable to have two pilots when flying off the controllers. One pilot will have the RC transmitter (safety pilot) the other will command velocities and altitude. You can use the "altitude hold" mode where you can set an initial velocity and then fly off the RC Transmitter 91 | 11) Now you should have a tuned estimator and controller that will fly RGBD and sonar measurements. 92 | 12) If you do want to follow setpoints, you can use the dubins_path package which will convert position setpoints to velocity trajectories. Read the documentation for dubins_path to get that setup. It will use the same gains you used to tune the controller. 93 | 94 | ## Vicon vs Optitrack 95 | 96 | When developing we used the Optitrack system to generate ground truth. Optitrack due to its popularity in the animation field produces estimates in the (EDN) coordinate frame. Hence the ros_vrpn_client is used to rotate it to the NED frame. If youre using VICON you will not need this since VICON reports estimates in NED frame. You can instead use the [vrpn_client_ros](http://wiki.ros.org/vrpn_client_ros) package. 97 | 98 | 99 | 100 | --------------------------------------------------------------------------------