From 2a233b7d13de6713bebf22d771a28a4faa11a6ac Mon Sep 17 00:00:00 2001 From: Ajay Shankar Date: Tue, 24 Nov 2020 17:59:31 -0600 Subject: [PATCH] Add build and run instructions to readme Include link to wiki --- README.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 925641d..3a88f40 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,48 @@ Freyja is a collection of four primary ROS packages: - `state_manager` : interfaces several input data sources (motion capture, gps, camera estimate) to produce one `state_vector` [denoted **x** in typical control schemes]. Some parts of state_vector are calculated (such as velocity), and some are merged from different callbacks. Also implements a collection of commonly used filters (Gaussian, LWMA, Median ..) - `lqg_control` : the core controller node that takes **x** from `state_manager`, a reference state **xr**, and calculates the optimal control required to regulate **x** to **xr**. Implements a standard LQR controller and a full state observer (Kalman) to function as a Linear Quadratic Gaussian (LQG) controller. - `autopilot_handler` : contains communication interfaces to autopilots. Currently supported autopilots are Pixhawk (with ArduCopter stack, px4 experimental) and Ascending Technologies. -- `freyja_trajectory_provider` : an example trajectory provider node that produces **xr**. In common use, this is typically suppressed (using a launch argument), and users will write their own custom trajectory node that represents their particular flight objectives. It is possible for **xr** to be simple discrete waypoints, piecewise continuous paths, or the product of an advanced trajectory planner that incorporates spatial and temporal shapes of trajectories. Path derivatives up to the 2nd order are supported. +- `freyja_trajectory_provider` : an example trajectory provider node that produces **xr**. In common use, this node is typically suppressed (using a launch argument), and users will write their own custom trajectory node that represents their particular flight objectives. It is possible for **xr** to be simple discrete waypoints, piecewise continuous paths, or the product of an advanced trajectory planner that incorporates spatial and temporal shapes of trajectories. Path derivatives up to the 2nd order are supported. + +## Build +Clone the repository into the `src/` directory of your ROS workspace. Other packages in your project (such as camera processing, machine learning, trajectory generators) will sit adjacent to `Freyja/`. A recommended directory structure would look like so: +```bash +- my_awesome_flight_project/ + | -- build/ + | -- devel/ + | -- src/ + | -- Freyja/ + | -- my_trajectory_provider/ + | -- my_image_classifier/ +``` +Run `catkin_make` or `catkin build` inside the project level directory (`my_awesome_flight_project/` in the example above). Freyja will be compiled alongside your other packages, and the build products are located within the common `build/` and `devel/` directories. + +## Run +Freyja includes a `freyja_controller.launch` file that spawns the constituent nodes, and accepts commonly used parameters as launch arguments. The simplest way to launch the full system is: +```sh +$> roslaunch src/Freyja/freyja_controller.launch total_mass:=1.2 start_rosbag:=true +``` +Here, `total_mass` and `start_rosbag` are two of the launch arguments; others may be provided as needed. When flying indoors, `vicon_topic` might be a commonly used and required argument. + +For bigger projects that involve more packages, prepare your own launch file, and include Freyja's launch file in it. +```xml + + + + + + + + + + + : + : + +``` +In the example above, the launch argument `use_external_trajectory` is set to true since you are expected to provide your own custom trajectory source (and not use Freyja's built-in examples). + +## Wiki +Check out [Freyja's wiki](https://github.com/unl-nimbus-lab/Freyja/wiki) to get more details on everything, from a basic multirotor build, to advanced configuration and set up, all the way to how trajectories can be written. ## License, Credits and Usage Freyja is developed in the [Nimbus Lab](https://nimbus.unl.edu), with rigorous testing under a multitude of operational scenarios and is used internally for various projects. Generous thanks to members who have tested and reported bugs, issues and feature limitations. The software is public under the GNU GPLv3 license. Please use wisely, and recommend improvements!