From 92a4145d0d60d5da5f4d916650333688b88c78ab Mon Sep 17 00:00:00 2001 From: madratman Date: Mon, 6 Apr 2020 19:19:10 -0700 Subject: [PATCH] [docs] see full commit msg for details - move all remaining docs to docs/ folder - index them in mkdocs/nav - move mkdocs.yml to root folder to fix nested docs/ dir issue - add ros, mavlinkcom, mavlinkcom mocap, domain randomization, mesh vertex buffer, infrared cam, unity to gh.io page - fix srv / msg links in airsim_ros_pkgs readme --- CHANGELOG.md | 117 +--------- CONTRIBUTING.md | 16 +- MavLinkCom/MavLinkMoCap/Readme.md | 29 +-- MavLinkCom/README.md | 219 +---------------- SUPPORT.md | 5 +- Unity/README.md | 130 +---------- build_docs.sh | 6 + docs/CHANGELOG.md | 116 +++++++++ docs/CONTRIBUTING.md | 17 ++ docs/SUPPORT.md | 6 + docs/Unity.md | 131 +++++++++++ docs/airsim_ros_pkgs.md | 162 +++++++++++++ docs/airsim_tutorial_pkgs.md | 60 +++++ docs/apis.md | 2 +- docs/build_windows.md | 2 +- docs/code_structure.md | 2 +- docs/create_issue.md | 4 +- docs/custom_unity_environments.md | 2 +- docs/mavlinkcom.md | 220 ++++++++++++++++++ .../mavlinkcom_design}/Design.dgml | 0 .../mavlinkcom_design}/FtpDesign.dgml | 0 .../mavlinkcom_design}/OffboardControl.dgml | 0 .../mavlinkcom_design}/images/example1.png | Bin .../mavlinkcom_design}/images/example2.png | Bin .../mavlinkcom_design}/images/example3.png | Bin .../mavlinkcom_design}/images/example4.png | Bin .../mavlinkcom_design}/images/overview.png | Bin docs/mavlinkcom_mocap.md | 28 +++ docs/mkdocs.yml | 181 -------------- docs/python.md | 3 - docs/use_precompiled.md | 2 +- mkdocs.yml | 115 +++++++++ ros/src/airsim_ros_pkgs/README.md | 161 +------------ ros/src/airsim_tutorial_pkgs/README.md | 59 +---- 34 files changed, 876 insertions(+), 919 deletions(-) create mode 100644 build_docs.sh create mode 100644 docs/CHANGELOG.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/SUPPORT.md create mode 100644 docs/Unity.md create mode 100644 docs/airsim_ros_pkgs.md create mode 100644 docs/airsim_tutorial_pkgs.md create mode 100644 docs/mavlinkcom.md rename {MavLinkCom/Design => docs/mavlinkcom_design}/Design.dgml (100%) rename {MavLinkCom/Design => docs/mavlinkcom_design}/FtpDesign.dgml (100%) rename {MavLinkCom/Design => docs/mavlinkcom_design}/OffboardControl.dgml (100%) rename {MavLinkCom/Design => docs/mavlinkcom_design}/images/example1.png (100%) rename {MavLinkCom/Design => docs/mavlinkcom_design}/images/example2.png (100%) rename {MavLinkCom/Design => docs/mavlinkcom_design}/images/example3.png (100%) rename {MavLinkCom/Design => docs/mavlinkcom_design}/images/example4.png (100%) rename {MavLinkCom/Design => docs/mavlinkcom_design}/images/overview.png (100%) create mode 100644 docs/mavlinkcom_mocap.md delete mode 100644 docs/mkdocs.yml delete mode 100644 docs/python.md create mode 100644 mkdocs.yml diff --git a/CHANGELOG.md b/CHANGELOG.md index b226285409..6545cf2c09 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,116 +1,3 @@ -# What's new +# Changelog -Below is summarized list of important changes. This does not include minor/less important changes or bug fixes or documentation update. This list updated every few months. For complete detailed changes, please review [commit history](https://github.com/Microsoft/AirSim/commits/master). - -### March 2020 -* Upgraded to Unreal Engine 4.24 - -### November, 2018 -* Added Weather Effects and [APIs](docs/apis.md#weather-apis) -* Added [Time of Day API](docs/apis.md#time-of-day-api) -* An experimental integration of [AirSim on Unity](https://github.com/Microsoft/AirSim/tree/master/Unity) is now available. Learn more in [Unity blog post](https://blogs.unity3d.com/2018/11/14/airsim-on-unity-experiment-with-autonomous-vehicle-simulation). -* [New environments](https://github.com/Microsoft/AirSim/releases/tag/v1.2.1): Forest, Plains (windmill farm), TalkingHeads (human head simulation), TrapCam (animal detection via camera) -* Highly efficient [NoDisplay view mode](https://github.com/Microsoft/AirSim/blob/master/docs/settings.md#viewmode) to turn off main screen rendering so you can capture images at high rate -* [Enable/disable sensors](https://github.com/Microsoft/AirSim/pull/1479) via settings -* [Lidar Sensor](docs/lidar.md) -* [Support for Flysky FS-SM100 RC](https://github.com/Microsoft/AirSim/commit/474214364676b6631c01b3ed79d00c83ba5bccf5) USB adapter -* Case Study: [Formula Student Technion Driverless](https://github.com/Microsoft/AirSim/wiki/technion) -* [Multi-Vehicle Capability](docs/multi_vehicle.md) -* [Custom speed units](https://github.com/Microsoft/AirSim/pull/1181) -* [ROS publisher](https://github.com/Microsoft/AirSim/pull/1135) -* [simSetObjectPose API](https://github.com/Microsoft/AirSim/pull/1161) -* [Character Control APIs](https://github.com/Microsoft/AirSim/blob/master/PythonClient/airsim/client.py#L137) (works on TalkingHeads binaries in release) -* [Arducopter Solo Support](https://github.com/Microsoft/AirSim/pull/1387) -* [Linux install without sudo access](https://github.com/Microsoft/AirSim/pull/1434) -* [Kinect like ROS publisher](https://github.com/Microsoft/AirSim/pull/1298) - - -### June, 2018 -* Development workflow doc -* Better Python 2 compatibility -* OSX setup fixes -* Almost complete rewrite of our APIs with new threading model, merging old APIs and creating few newer ones - -### April, 2018 -* Upgraded to Unreal Engine 4.18 and Visual Studio 2017 -* API framework refactoring to support world-level APIs -* Latest PX4 firmware now supported -* CarState with more information -* ThrustMaster wheel support -* pause and continueForTime APIs for drone as well as car -* Allow drone simulation run at higher clock rate without any degradation -* Forward-only mode fully functional for drone (do orbits while looking at center) -* Better PID tuning to reduce wobble for drones -* Ability to set arbitrary vehicle blueprint for drone as well as car -* gimbal stabilization via settings -* Ability to segment skinned and skeletal meshes by their name -* moveByAngleThrottle API -* Car physics tuning for better maneuverability -* Configure additional cameras via settings -* Time of day with geographically computed sun position -* Better car steering via keyboard -* Added MeshNamingMethod in segmentation setting -* gimbal API -* getCameraParameters API -* Ability turn off main rendering to save GPU resources -* Projection mode for capture settings -* getRCData, setRCData APIs -* Ability to turn off segmentation using negative IDs -* OSX build improvements -* Segmentation working for very large environments with initial IDs -* Better and extensible hash calculation for segmentation IDs -* Extensible PID controller for custom integration methods -* Sensor architecture now enables renderer specific features like ray casting -* Laser altimeter sensor - - -### Jan 2018 -* Config system rewrite, enable flexible config we are targeting in future -* Multi-Vehicle support Phase 1, core infrastructure changes -* MacOS support -* Infrared view -* 5 types of noise and interference for cameras -* WYSIWIG capture settings for cameras, preview recording settings in main view -* Azure support Phase 1, enable configurability of instances for headless mode -* Full kinematics APIs, ability to get pose, linear and angular velocities + accelerations via APIs -* Record multiple images from multiple cameras -* New segmentation APIs, ability to set configure object IDs, search via regex -* New object pose APIs, ability to get pose of objects (like animals) in environment -* Camera infrastructure enhancements, ability to add new image types like IR with just few lines -* Clock speed APIs for drone as well as car, simulation can be run with speed factor of 0 < x < infinity -* Support for Logitech G920 wheel -* Physics tuning of the car, Car doesn’t roll over, responds to steering with better curve, releasing gas paddle behavior more realistic -* Debugging APIs -* Stress tested to 24+ hours of continuous runs -* Support for Landscape and sky segmentation -* Manual navigation with accelerated controls in CV mode, user can explore environment much more easily -* Collison APIs -* Recording enhancements, log several new data points including ground truth, multiple images, controls state -* Planner and Perspective Depth views -* Disparity view -* New Image APIs supports float, png or numpy formats -* 6 config settings for image capture, ability to set auto-exposure, motion blur, gamma etc -* Full multi-camera support through out including sub-windows, recording, APIs etc -* Command line script to build all environments in one shot -* Remove submodules, use rpclib as download - -### Nov 2017 -* We now have the [car model](docs/using_car.md). -* No need to build the code. Just download [binaries](https://github.com/Microsoft/AirSim/releases) and you are good to go! -* The [reinforcement learning example](docs/reinforcement_learning.md) with AirSim -* New built-in flight controller called [simple_flight](docs/simple_flight.md) that "just works" without any additional setup. It is also now *default*. -* AirSim now also generates [depth as well as disparity images](docs/image_apis.md) that is in camera plan. -* We also have official Linux build now! - -## Sep 2017 -- We have added [car model](docs/using_car.md)! - -## Aug 2017 -- [simple_flight](docs/simple_flight.md) is now default flight controller for drones. If you want to use PX4, you will need to modify settings.json as per [PX4 setup doc](docs/px4_setup.md). -- Linux build is official and currently uses Unreal 4.17 due to various bug fixes required -- ImageType enum has breaking changes with several new additions and clarifying existing ones -- SubWindows are now configurable from settings.json -- PythonClient is now complete and has parity with C++ APIs. Some of these would have breaking changes. - -## Feb 2017 -- First release! \ No newline at end of file +This page has moved [here](https://github.com/microsoft/AirSim/blob/master/docs/CHANGELOG.md). \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 866634956e..99687b2855 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,17 +1,3 @@ # Contributing -## Quick Start -- Please read our [short and sweet coding guidelines](docs/coding_guidelines.md). -- For big changes such as adding new feature or refactoring, [file an issue first](https://github.com/Microsoft/AirSim/issues). -- Use our [recommended development workflow](docs/dev_workflow.md) to make changes and test it. -- Use [usual steps](https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/) to make contributions just like other GitHub projects. If you are not familiar with Git Branch-Rebase-Merge workflow, please [read this first](http://shitalshah.com/p/git-workflow-branch-rebase-squash-merge/). - -## Checklist -- Use same style and formatting as rest of code even if it's not your preferred one. -- Change any documentation that goes with code changes. -- Do not include OS specific header files or new 3rd party dependencies. -- Keep your pull request small, ideally under 10 files. -- Make sure you don't include large binary files. -- When adding new includes, make dependency is absolutely necessary. -- Rebase your branch frequently with master (once every 2-3 days is ideal). -- Make sure your code would compile on Windows, Linux and OSX. +This page has moved [here](https://github.com/microsoft/AirSim/blob/master/docs/CONTRIBUTING.md). \ No newline at end of file diff --git a/MavLinkCom/MavLinkMoCap/Readme.md b/MavLinkCom/MavLinkMoCap/Readme.md index cb5924778c..073408f79f 100644 --- a/MavLinkCom/MavLinkMoCap/Readme.md +++ b/MavLinkCom/MavLinkMoCap/Readme.md @@ -1,30 +1,3 @@ # Welcome to MavLinkMoCap -This folder contains the MavLinkMoCap library which connects to a OptiTrack camera system -for accurate indoor location. - -## Dependencies: -* [OptiTrack Motive](http://www.optitrack.com/products/motive/). -* [MavLinkCom](../MavLinkCom). - -### Setup RigidBody - -First you need to define a RigidBody named 'Quadrocopter' using Motive. -See [Rigid_Body_Tracking](http://wiki.optitrack.com/index.php?title=Rigid_Body_Tracking). - -### MavLinkTest - -Use MavLinkTest to talk to your PX4 drone, with "-server:addr:port", for example, when connected -to drone wifi use: - - MavLinkMoCap -server:10.42.0.228:14590 "-project:D:\OptiTrack\Motive Project 2016-12-19 04.09.42 PM.ttp" - -This publishes the ATT_POS_MOCAP messages and you can proxy those through to the PX4 by running -MavLinkTest on the dronebrain using: - - MavLinkTest -serial:/dev/ttyACM0,115200 -proxy:10.42.0.228:14590 - -Now the drone will get the ATT_POS_MOCAP and you should see the light turn green meaning it is -now has a home position and is ready to fly. - - +This page has moved [here](https://github.com/microsoft/AirSim/blob/master/docs/mavlinkcom_mocap.md). \ No newline at end of file diff --git a/MavLinkCom/README.md b/MavLinkCom/README.md index bcd0d466db..6bd67cea31 100644 --- a/MavLinkCom/README.md +++ b/MavLinkCom/README.md @@ -1,220 +1,3 @@ # Welcome to MavLinkCom -MavLinkCom is a cross-platform C++ library that helps connect to and communicate with [MavLink](https://github.com/mavlink/mavlink) based vehicles. -Specifically this library is designed to work well with [PX4](https://github.com/PX4/Firmware) based drones. - -## Design - -You can view and edit the [Design.dgml](Design/Design.dgml) diagram in Visual Studio. -![Overview](Design/images/overview.png) - -The following are the most important classes in this library. - -### MavLinkNode - -This is the base class for all MavLinkNodes (subclasses include MavLinkVehicle, MavLinkVideoClient and MavLinkVideoServer). -The node connects to your mavlink enabled vehicle via a MavLinkConnection and provides methods for sending MavLinkMessages and MavLinkCommands -and for subscribing to receive messages. This base class also stores the local system id and component id your app wants to use to identify -itself to your remove vehicle. You can also call startHeartbeat to send regular heartbeat messages to keep the connection alive. - -### MavLinkMessage - -This is the encoded MavLinkMessage. For those who have used the mavlink.h C API, this is similar to mavlink_message_t. You do -not create these manually, they are encoded from a strongly typed MavLinkMessageBase subclass. - -### Strongly typed message and command classes - -The MavLinkComGenerator parses the mavlink common.xml message definitions and generates all the MavLink* MavLinkMessageBase subclasses -as well as a bunch of handy mavlink enums and a bunch of strongly typed MavLinkCommand subclasses. - -### MavLinkMessageBase - -This is the base class for a set of strongly typed message classes that are code generated by the MavLinkComGenerator project. -This replaces the C messages defined in the mavlink C API and provides a slightly more object oriented way to send and receive messages -via sendMessage on MavLinkNode. These classes have encode/decode methods that convert to and from the MavLinkMessage class. - -### MavLinkCommand - -This is the base class for a set of strongly typed command classes that are code generated by the MavLinkComGenerator project. -This replaces the C definitions defined in the mavlink C API and provides a more object oriented way to send commands via the sendCommand -method on MavLinkNode. The MavLinkNode takes care of turning these into the underlying mavlink COMMAND_LONG message. - -### MavLinkConnection - -This class provides static helper methods for creating connections to remote MavLink nodes, over serial ports, as well as UDP, or TCP sockets. -This class provides a way to subscribe to receive messages from that node in a pub/sub way so you can have multiple subscribers on the -same connection. MavLinkVehicle uses this to track various messages that define the overall vehicle state. - -### MavLinkVehicle - -MavLinkVehicle is a MavLinkNode that tracks various messages that define the overall vehicle state and provides a VehicleState struct -containing a snapshot of that state, including home position, current orientation, local position, global position, and so on. -This class also provides a bunch of helper methods that wrap commonly used commands providing simple method calls to do things like -arm, disarm, takeoff, land, go to a local coordinate, and fly under offbaord control either by position or velocity control. - -### MavLinkTcpServer - -This helper class provides a way to setup a "server" that accepts MavLinkConnections from remote nodes. You can use this class -to get a connection that you can then give to MavLinkVideoServer to serve images over MavLink. - -### MavLinkFtpClient - -This helper class takes a given MavLinkConnection and provides FTP client support for the MAVLINK_MSG_ID_FILE_TRANSFER_PROTOCOL -for vehicles that support the FTP capability. This class provides simple methods to list directory contents, and the get and put -files. - -### MavLinkVideoClient - -This helper class takes a given MavLinkConnection and provides helper methods for requesting video from remote node and -packaging up the MAVLINK_MSG_ID_DATA_TRANSMISSION_HANDSHAKE and MAVLINK_MSG_ID_ENCAPSULATED_DATA messages into simple to use -MavLinkVideoFrames. - -### MavLinkVideoServer - -This helper class takes a given MavLinkConnection and provides the server side of the MavLinkVideoClient protocol, including helper methods -for notifying when there is a video request to process (hasVideoRequest) and a method to send video frames (sendFrame) which -will generate the right MAVLINK_MSG_ID_DATA_TRANSMISSION_HANDSHAKE and MAVLINK_MSG_ID_ENCAPSULATED_DATA sequence. - -## Examples - -The following code from the UnitTest project shows how to connect to a [Pixhawk](http://www.pixhawk.org/) flight controller over USB serial port, -then wait for the first heartbeat message to be received: - - auto connection = MavLinkConnection::connectSerial("drone", "/dev/ttyACM0", 115200, "sh /etc/init.d/rc.usb\n"); - MavLinkHeartbeat heartbeat; - if (!waitForHeartbeat(10000, heartbeat)) { - throw std::runtime_error("Received no heartbeat from PX4 after 10 seconds"); - } - - -The following code connects to serial port, and then forwards all messages to and from QGroundControl to that drone using another connection -that is joined to the drone stream. - - auto droneConnection = MavLinkConnection::connectSerial("drone", "/dev/ttyACM0", 115200, "sh /etc/init.d/rc.usb\n"); - auto proxyConnection = MavLinkConnection::connectRemoteUdp("qgc", "127.0.0.1", "127.0.0.1", 14550); - droneConnection->join(proxyConnection); - -The following code then takes that connection and turns on heartBeats and starts tracking vehicle information using local -system id 166 and component id 1. - - auto vehicle = std::make_shared(166, 1); - vehicle->connect(connection); - vehicle->startHeartbeat(); - - std::this_thread::sleep_for(std::chrono::seconds(5)); - - VehicleState state = vehicle->getVehicleState(); - printf("Home position is %s, %f,%f,%f\n", state.home.is_set ? "set" : "not set", - state.home.global_pos.lat, state.home.global_pos.lon, state.home.global_pos.alt); - -The following code uses the vehicle object to arm the drone and take off and wait for the takeoff altitude to be reached: - - bool rc = false; - if (!vehicle->armDisarm(true).wait(3000, &rc) || !rc) { - printf("arm command failed\n"); - return; - } - if (!vehicle->takeoff(targetAlt).wait(3000, &rc) || !rc) { - printf("takeoff command failed\n"); - return; - } - int version = vehicle->getVehicleStateVersion(); - while (true) { - int newVersion = vehicle->getVehicleStateVersion(); - if (version != newVersion) { - VehicleState state = vehicle->getVehicleState(); - float alt = state.local_est.pos.z; - if (alt >= targetAlt - delta && alt <= targetAlt + delta) - { - reached = true; - printf("Target altitude reached\n"); - break; - } - } else { - std::this_thread::sleep_for(std::chrono::milliseconds(10)); - } - } - -The following code uses offboard control to make the drone fly in a circle with camera pointed at the center. -Here we use the subscribe method to check each new local position message to indicate so we can compute the new -velocity vector as soon as that new position is received. We request a high rate for those messages using -setMessageInterval to ensure smooth circular orbit. - - vehicle->setMessageInterval((int)MavLinkMessageIds::MAVLINK_MSG_ID_LOCAL_POSITION_NED, 30); - vehicle->requestControl(); - int subscription = vehicle->getConnection()->subscribe( - [&](std::shared_ptr connection, const MavLinkMessage& m) { - if (m.msgid == (int)MavLinkMessageIds::MAVLINK_MSG_ID_LOCAL_POSITION_NED) - { - float x = localPos.x; - float y = localPos.y; - float dx = x - cx; - float dy = y - cy; - float angle = atan2(dy, dx); - if (angle < 0) angle += M_PI * 2; - float tangent = angle + M_PI_2; - double newvx = orbitSpeed * cos(tangent); - double newvy = orbitSpeed * sin(tangent); - float heading = angle + M_PI; - vehicle->moveByLocalVelocityWithAltHold(newvx, newvy, altitude, true, heading); - } - }); - -The following code stops flying the drone in offboard mode and tells the drone to loiter at its current location. -This version of the code shows how to use the AsyncResult without blocking on a wait call. - - vehicle->releaseControl(); - if (vehicle->loiter().then([=](bool rc) { - printf("loiter command %s\n", rc ? "succeeded" : "failed"); - } - -The following code gets all configurable parameters from the drone and prints them: - - auto list = vehicle->getParamList(); - auto end = list.end(); - int count = 0; - for (auto iter = list.begin(); iter < end; iter++) - { - count++; - MavLinkParameter p = *iter; - if (p.type == MAV_PARAM_TYPE_REAL32 || p.type == MAV_PARAM_TYPE_REAL64) { - printf("%s=%f\n", p.name.c_str(), p.value); - } - else { - printf("%s=%d\n", p.name.c_str(), static_cast(p.value)); - } - } - -The following code sets a parameter on the Pixhawk to disable the USB safety check (this is handy if you are controlling -the Pixhawk over USB using another onboard computer that is part of the drone itself). You should NOT do this if you -are connecting your PC or laptop to the drone over USB. - - MavLinkParameter p; - p.name = "CBRK_USB_CHK"; - p.value = 197848; - if (!vehicle->setParameter(p).wait(3000,&rc) || !rc) { - printf("Setting the CBRK_USB_CHK failed"); - } - -MavLinkVehicle actually has a helper method for this called allowFlightControlOverUsb, so now you know how it is implemented :-) - -## Advanced Connections - -You can wire up different configurations of mavlink pipelines using the MavLinkConnection class "join" method as shown below. - -Example 1, we connect to PX4 over serial, and proxy those messages through to QGroundControl and the LogViewer who are listening on remote ports. - -![Serial to QGC](Design/images/example1.png) - -Example 2: simulation can talk to jMavSim and jMavSim connects to PX4. jMavSim can also manage multiple connections, so it can talk to unreal simulator. -Another MavLinkConnection can be joined to proxy connections that jMavSim doesn't support, like the LogViewer or a remote camera node. - -![Serial to QGC](Design/images/example2.png) - -Example 3: we use MavLinkConnection to connect to PX4 over serial, then join additional connections for all our remote nodes including jMavSim. - -![Serial to QGC](Design/images/example3.png) - -Example 4: We can also do distributed systems to control the drone remotely: - -![Serial to QGC](Design/images/example4.png) +This page has moved [here](https://github.com/microsoft/AirSim/blob/master/docs/mavlinkcom.md). \ No newline at end of file diff --git a/SUPPORT.md b/SUPPORT.md index ea1e7658b9..4580e60494 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,6 +1,3 @@ # Support -We highly recommend to take a look at source code and contribute to the project. Due to large number of incoming feature request we may not be able to get to your request in your desired timeframe. So please [contribute](CONTRIBUTING.md) :). - -* [Join AirSim Facebook Group](https://www.facebook.com/groups/1225832467530667/) -* [File GitHub Issue](https://github.com/Microsoft/AirSim/issues) \ No newline at end of file +This page has moved [here](https://github.com/microsoft/AirSim/blob/master/docs/SUPPORT.md). diff --git a/Unity/README.md b/Unity/README.md index 65834bf439..c9d5cd3ae8 100644 --- a/Unity/README.md +++ b/Unity/README.md @@ -1,131 +1,3 @@ # AirSim on Unity -* AirSim on Unity allows you to run your simulators in the [Unity Engine](https://unity3d.com/). This project comes with some sample Unity projects and a wrapper around the AirLib library to run as a [native plugin](https://docs.unity3d.com/Manual/NativePlugins.html) in Unity. -* Included are two basic Unity Projects, one for a Car simulator and another for a Drone simulator. They are meant to be lightweight, and can be used to verify your setup is correct. -* Check out the [Unity blogpost](https://blogs.unity3d.com/2018/11/14/airsim-on-unity-experiment-with-autonomous-vehicle-simulation/) for overview on the release. - -### Warning: Experimental Release -This project is still in early development, expect some rough edges. We are working to fully support the full AirLib API and feature set, but some things may be missing. [Click here](../docs/unity_api_support.md) for the list of currently supported APIs. - -## Windows -### Building from source -#### Install Unity -* Download **Unity Hub** from [this page](https://unity3d.com/get-unity/download). -* Install **Unity 2018.2.15f1** using the Unity Hub. [Detailed instructions here](https://docs.unity3d.com/Manual/GettingStartedInstallingHub.html). -* Note: If you are using Unity for the first time, check out [the Getting started guide](https://docs.unity3d.com/Manual/GettingStarted.html). The [Unity User Manual](https://docs.unity3d.com/Manual/UnityManual.html) has additional tips, resources, and FAQs. - -#### Build Airsim -* Install Visual Studio 2017. -**Make sure** to select **VC++** and **Windows SDK 8.1** while installing VS 2017. - -* Start `x64 Native Tools Command Prompt for VS 2017`. -* Clone the repo: `git clone https://github.com/Microsoft/AirSim.git`, and go the AirSim directory by `cd AirSim`. -* Run `build.cmd` from the command line. - -#### Build Unity Project -* Go inside the AirSim\Unity directory: `cd Unity`. -* Build the unity project: `build.cmd`. -* Additionally, there is a free environment `Windridge City` which you can download from [Unity Asset Store](https://assetstore.unity.com/packages/3d/environments/roadways/windridge-city-132222). And, of course, you can always create your own environment. - -## Linux -#### Dependencies -``` -sudo apt-get install libboost-all-dev -``` -#### Download and Install Unity for Linux -Warning: Unity Editor for Linux is still in Beta. Expect some rough edges. - -* **Download** Unity editor version `2019.1.0f2` - ```shell - wget https://beta.unity3d.com/download/292b93d75a2c/UnitySetup-2019.1.0f2 - ``` - Note: While the latest version of linux build of Unity can be found on the last post of [this thread](https://forum.unity.com/threads/unity-on-linux-release-notes-and-known-issues.350256/page-2#post-4458286), we recommend `2019.1.0f2`. - -* **Install** the editor - ```shell - chmod +x UnitySetup-2019.1.0f2 - ./UnitySetup-2019.1.0f2 - ``` - -#### Build Airsim -``` -git clone https://github.com/Microsoft/AirSim.git; -cd AirSim; -./setup.sh; -./build.sh -``` - -#### Generate AirsimWrapper Shared Library -``` -cd AirSim/Unity -./build.sh -``` - -This will generate the necessary shared library and copy it to the UnityDemo Plugins folder. - -## Usage -* Start Unity and click `Open project`. -* Select the folder `AirSim\Unity\UnityDemo`, and then hit the button `Select Folder`. -* In the bottom pane, Click on `Projects`->`Assets`->`Scenes`. Then, **Double-click** on `SimModeSelector`. This will load the SimModeSelector scene into the scene hierarchy pane. *DO NOT* add CarDemo or DroneDemo scene into the scene hierarchy pane. -* Hit the play button to start the simulation (and hit play again to stop the simulation. . -* Alternatively, you can change the SimMode in your `Settings.json` file. (You can read more about [`Settings.json` here](https://github.com/Microsoft/AirSim/blob/master/docs/settings.md)) -* Controlling the car: -Use `WASD` or the `Arrow keys` or the AirSim client. -* Controlling the drone: -Keyboard control is not currently available for drone flight. -* Changing camera views: -Keys `0`, `1`, `2`, `3` are used to toggle windows of different camera views. -* Recording simulation data: -Press *Record* button(Red button) located at the right bottom corner of the screen, to toggle recording of the simulation data. The recorded data can be found at `Documents\AirSim\(Date of recording)` on Windows and `~/Documents/AirSim/(Date of recording)` on Linux. -## Building Custom Environments For AirSim -To use environments other than `UnityDemo`, follow the instructions written [here](../docs/custom_unity_environments.md) -## Cross-Compiling to Linux -Unity Editor supports compiling projects to Linux systems. -After following the steps to build AirSim and Unity on Windows, do the following: - -#### Linux Pre-Requisites -Before being able to run Unity Binaries with the Airsim plugin, be sure have airsim and airsim unity built on your linux machine by following the Linux build steps above. - -### Package UnityDemo Binary On Windows - -#### Install Necessary Components -In order to package your project for linux, the **Linux Build Support** Unity add-on must be installed. -* Open **Unity Hub**, and click the **Add component** button in the dropdown window under **more options** to the right of your **Unity 2018.2.15f1** tab. -![Adding components](../docs/images/unity_linux_components_1.PNG) -* Make sure the **Linux Build Support** Platform is selected -![Adding components](../docs/images/unity_linux_components_2.PNG) -Once this component is successfully installed, you are ready to build Unity Projects for Linux! - -#### Build the Project -* On your Windows machine, build the Unity Demo by navigating to the build settings option in the toolbar ```File -> Build Settings``` -* Make sure the following scenes are set to be built: - 1. SimModeSelector - 2. CarDemo - 3. DroneDemo -* Set the target operating system to linux, and choose the version appropriate for your system (x86 vs x86_64) -* Click ```Build``` -* Transport the built project as well as the generated folder ```"{project_name}_Data"``` to your linux machine - -#### Copy The AirsimWrapper Library to the Project Plugins folder -* On your linux machine, navigate to your AirSim repository, and run the following commands in a terminal window: - ``` - cp Unity/linux-build/libAirsimWrapper.so path/to/your/project/{project_name}_Data/Plugins/{os_version} - ``` -This will generate the necessary shared library to allow Airsim to communicate with Unity and copy it to the plugins folder of your project binary. - -#### Run the Project Binary -* Open a terminal and navigate to your project directory -* Set your project binary as an executable file: -``` -chmod +x "{project_name}.{configuration}" -``` -* Run the binary file -``` -./{project_name}.{configuration} -``` -### Using Airsim API -* For quickstart with the Python APIs for the car or the drone, simply run the [`hello_car.py`](https://github.com/Microsoft/AirSim/blob/master/PythonClient/car/hello_car.py) or the [`hello_drone.py`](https://github.com/Microsoft/AirSim/blob/master/PythonClient/multirotor/hello_drone.py) script accordingly. -* Details of the AirSim C++ and Python APIs are [here](https://github.com/Microsoft/AirSim/blob/master/docs/apis.md). - -### Acknowledgements -* The drone object was provided by user 31415926 on [sketchfab](https://sketchfab.com/models/055841df0fb24cd4abde06a91f7d360a). It is licensed under the [CC License](https://creativecommons.org/licenses/by/4.0/). +This page has moved [here](https://github.com/microsoft/AirSim/blob/master/docs/Unity.md) \ No newline at end of file diff --git a/build_docs.sh b/build_docs.sh new file mode 100644 index 0000000000..cf81bc8cd5 --- /dev/null +++ b/build_docs.sh @@ -0,0 +1,6 @@ +# make symlinks to doc folder to make mkdocs happy +ln -s ${PWD}/CHANGELOG.md ${PWD}/docs/CHANGELOG.md +ln -s ${PWD}/CONTRIBUTING.md ${PWD}/docs/CONTRIBUTING.md +ln -s ${PWD}/ISSUE_TEMPLATE.md ${PWD}/docs/ISSUE_TEMPLATE.md +ln -s ${PWD}/SUPPORT.md ${PWD}/docs/SUPPORT.md +ln -s ${PWD}/README.md ${PWD}/docs/dREADME.md \ No newline at end of file diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000000..2b7063078a --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,116 @@ +# What's new + +Below is summarized list of important changes. This does not include minor/less important changes or bug fixes or documentation update. This list updated every few months. For complete detailed changes, please review [commit history](https://github.com/Microsoft/AirSim/commits/master). + +### March 2020 +* Upgraded to Unreal Engine 4.24 + +### November, 2018 +* Added Weather Effects and [APIs](apis.md#weather-apis) +* Added [Time of Day API](apis.md#time-of-day-api) +* An experimental integration of [AirSim on Unity](https://github.com/Microsoft/AirSim/tree/master/Unity) is now available. Learn more in [Unity blog post](https://blogs.unity3d.com/2018/11/14/airsim-on-unity-experiment-with-autonomous-vehicle-simulation). +* [New environments](https://github.com/Microsoft/AirSim/releases/tag/v1.2.1): Forest, Plains (windmill farm), TalkingHeads (human head simulation), TrapCam (animal detection via camera) +* Highly efficient [NoDisplay view mode](https://github.com/Microsoft/AirSim/blob/master/docs/settings.md#viewmode) to turn off main screen rendering so you can capture images at high rate +* [Enable/disable sensors](https://github.com/Microsoft/AirSim/pull/1479) via settings +* [Lidar Sensor](lidar.md) +* [Support for Flysky FS-SM100 RC](https://github.com/Microsoft/AirSim/commit/474214364676b6631c01b3ed79d00c83ba5bccf5) USB adapter +* Case Study: [Formula Student Technion Driverless](https://github.com/Microsoft/AirSim/wiki/technion) +* [Multi-Vehicle Capability](multi_vehicle.md) +* [Custom speed units](https://github.com/Microsoft/AirSim/pull/1181) +* [ROS publisher](https://github.com/Microsoft/AirSim/pull/1135) +* [simSetObjectPose API](https://github.com/Microsoft/AirSim/pull/1161) +* [Character Control APIs](https://github.com/Microsoft/AirSim/blob/master/PythonClient/airsim/client.py#L137) (works on TalkingHeads binaries in release) +* [Arducopter Solo Support](https://github.com/Microsoft/AirSim/pull/1387) +* [Linux install without sudo access](https://github.com/Microsoft/AirSim/pull/1434) +* [Kinect like ROS publisher](https://github.com/Microsoft/AirSim/pull/1298) + + +### June, 2018 +* Development workflow doc +* Better Python 2 compatibility +* OSX setup fixes +* Almost complete rewrite of our APIs with new threading model, merging old APIs and creating few newer ones + +### April, 2018 +* Upgraded to Unreal Engine 4.18 and Visual Studio 2017 +* API framework refactoring to support world-level APIs +* Latest PX4 firmware now supported +* CarState with more information +* ThrustMaster wheel support +* pause and continueForTime APIs for drone as well as car +* Allow drone simulation run at higher clock rate without any degradation +* Forward-only mode fully functional for drone (do orbits while looking at center) +* Better PID tuning to reduce wobble for drones +* Ability to set arbitrary vehicle blueprint for drone as well as car +* gimbal stabilization via settings +* Ability to segment skinned and skeletal meshes by their name +* moveByAngleThrottle API +* Car physics tuning for better maneuverability +* Configure additional cameras via settings +* Time of day with geographically computed sun position +* Better car steering via keyboard +* Added MeshNamingMethod in segmentation setting +* gimbal API +* getCameraParameters API +* Ability turn off main rendering to save GPU resources +* Projection mode for capture settings +* getRCData, setRCData APIs +* Ability to turn off segmentation using negative IDs +* OSX build improvements +* Segmentation working for very large environments with initial IDs +* Better and extensible hash calculation for segmentation IDs +* Extensible PID controller for custom integration methods +* Sensor architecture now enables renderer specific features like ray casting +* Laser altimeter sensor + + +### Jan 2018 +* Config system rewrite, enable flexible config we are targeting in future +* Multi-Vehicle support Phase 1, core infrastructure changes +* MacOS support +* Infrared view +* 5 types of noise and interference for cameras +* WYSIWIG capture settings for cameras, preview recording settings in main view +* Azure support Phase 1, enable configurability of instances for headless mode +* Full kinematics APIs, ability to get pose, linear and angular velocities + accelerations via APIs +* Record multiple images from multiple cameras +* New segmentation APIs, ability to set configure object IDs, search via regex +* New object pose APIs, ability to get pose of objects (like animals) in environment +* Camera infrastructure enhancements, ability to add new image types like IR with just few lines +* Clock speed APIs for drone as well as car, simulation can be run with speed factor of 0 < x < infinity +* Support for Logitech G920 wheel +* Physics tuning of the car, Car doesn’t roll over, responds to steering with better curve, releasing gas paddle behavior more realistic +* Debugging APIs +* Stress tested to 24+ hours of continuous runs +* Support for Landscape and sky segmentation +* Manual navigation with accelerated controls in CV mode, user can explore environment much more easily +* Collison APIs +* Recording enhancements, log several new data points including ground truth, multiple images, controls state +* Planner and Perspective Depth views +* Disparity view +* New Image APIs supports float, png or numpy formats +* 6 config settings for image capture, ability to set auto-exposure, motion blur, gamma etc +* Full multi-camera support through out including sub-windows, recording, APIs etc +* Command line script to build all environments in one shot +* Remove submodules, use rpclib as download + +### Nov 2017 +* We now have the [car model](using_car.md). +* No need to build the code. Just download [binaries](https://github.com/Microsoft/AirSim/releases) and you are good to go! +* The [reinforcement learning example](reinforcement_learning.md) with AirSim +* New built-in flight controller called [simple_flight](simple_flight.md) that "just works" without any additional setup. It is also now *default*. +* AirSim now also generates [depth as well as disparity images](image_apis.md) that is in camera plan. +* We also have official Linux build now! + +## Sep 2017 +- We have added [car model](using_car.md)! + +## Aug 2017 +- [simple_flight](simple_flight.md) is now default flight controller for drones. If you want to use PX4, you will need to modify settings.json as per [PX4 setup doc](px4_setup.md). +- Linux build is official and currently uses Unreal 4.17 due to various bug fixes required +- ImageType enum has breaking changes with several new additions and clarifying existing ones +- SubWindows are now configurable from settings.json +- PythonClient is now complete and has parity with C++ APIs. Some of these would have breaking changes. + +## Feb 2017 +- First release! \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000000..66cbd63d45 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,17 @@ +# Contributing + +## Quick Start +- Please read our [short and sweet coding guidelines](coding_guidelines.md). +- For big changes such as adding new feature or refactoring, [file an issue first](https://github.com/Microsoft/AirSim/issues). +- Use our [recommended development workflow](dev_workflow.md) to make changes and test it. +- Use [usual steps](https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/) to make contributions just like other GitHub projects. If you are not familiar with Git Branch-Rebase-Merge workflow, please [read this first](http://shitalshah.com/p/git-workflow-branch-rebase-squash-merge/). + +## Checklist +- Use same style and formatting as rest of code even if it's not your preferred one. +- Change any documentation that goes with code changes. +- Do not include OS specific header files or new 3rd party dependencies. +- Keep your pull request small, ideally under 10 files. +- Make sure you don't include large binary files. +- When adding new includes, make dependency is absolutely necessary. +- Rebase your branch frequently with master (once every 2-3 days is ideal). +- Make sure your code would compile on Windows, Linux and OSX. diff --git a/docs/SUPPORT.md b/docs/SUPPORT.md new file mode 100644 index 0000000000..ea1e7658b9 --- /dev/null +++ b/docs/SUPPORT.md @@ -0,0 +1,6 @@ +# Support + +We highly recommend to take a look at source code and contribute to the project. Due to large number of incoming feature request we may not be able to get to your request in your desired timeframe. So please [contribute](CONTRIBUTING.md) :). + +* [Join AirSim Facebook Group](https://www.facebook.com/groups/1225832467530667/) +* [File GitHub Issue](https://github.com/Microsoft/AirSim/issues) \ No newline at end of file diff --git a/docs/Unity.md b/docs/Unity.md new file mode 100644 index 0000000000..1c42e1d305 --- /dev/null +++ b/docs/Unity.md @@ -0,0 +1,131 @@ +# AirSim on Unity + +* AirSim on Unity allows you to run your simulators in the [Unity Engine](https://unity3d.com/). This project comes with some sample Unity projects and a wrapper around the AirLib library to run as a [native plugin](https://docs.unity3d.com/Manual/NativePlugins.html) in Unity. +* Included are two basic Unity Projects, one for a Car simulator and another for a Drone simulator. They are meant to be lightweight, and can be used to verify your setup is correct. +* Check out the [Unity blogpost](https://blogs.unity3d.com/2018/11/14/airsim-on-unity-experiment-with-autonomous-vehicle-simulation/) for overview on the release. + +### Warning: Experimental Release +This project is still in early development, expect some rough edges. We are working to fully support the full AirLib API and feature set, but some things may be missing. [Click here](unity_api_support.md) for the list of currently supported APIs. + +## Windows +### Building from source +#### Install Unity +* Download **Unity Hub** from [this page](https://unity3d.com/get-unity/download). +* Install **Unity 2018.2.15f1** using the Unity Hub. [Detailed instructions here](https://docs.unity3d.com/Manual/GettingStartedInstallingHub.html). +* Note: If you are using Unity for the first time, check out [the Getting started guide](https://docs.unity3d.com/Manual/GettingStarted.html). The [Unity User Manual](https://docs.unity3d.com/Manual/UnityManual.html) has additional tips, resources, and FAQs. + +#### Build Airsim +* Install Visual Studio 2017. +**Make sure** to select **VC++** and **Windows SDK 8.1** while installing VS 2017. + +* Start `x64 Native Tools Command Prompt for VS 2017`. +* Clone the repo: `git clone https://github.com/Microsoft/AirSim.git`, and go the AirSim directory by `cd AirSim`. +* Run `build.cmd` from the command line. + +#### Build Unity Project +* Go inside the AirSim\Unity directory: `cd Unity`. +* Build the unity project: `build.cmd`. +* Additionally, there is a free environment `Windridge City` which you can download from [Unity Asset Store](https://assetstore.unity.com/packages/3d/environments/roadways/windridge-city-132222). And, of course, you can always create your own environment. + +## Linux +#### Dependencies +``` +sudo apt-get install libboost-all-dev +``` +#### Download and Install Unity for Linux +Warning: Unity Editor for Linux is still in Beta. Expect some rough edges. + +* **Download** Unity editor version `2019.1.0f2` + ```shell + wget https://beta.unity3d.com/download/292b93d75a2c/UnitySetup-2019.1.0f2 + ``` + Note: While the latest version of linux build of Unity can be found on the last post of [this thread](https://forum.unity.com/threads/unity-on-linux-release-notes-and-known-issues.350256/page-2#post-4458286), we recommend `2019.1.0f2`. + +* **Install** the editor + ```shell + chmod +x UnitySetup-2019.1.0f2 + ./UnitySetup-2019.1.0f2 + ``` + +#### Build Airsim +``` +git clone https://github.com/Microsoft/AirSim.git; +cd AirSim; +./setup.sh; +./build.sh +``` + +#### Generate AirsimWrapper Shared Library +``` +cd AirSim/Unity +./build.sh +``` + +This will generate the necessary shared library and copy it to the UnityDemo Plugins folder. + +## Usage +* Start Unity and click `Open project`. +* Select the folder `AirSim\Unity\UnityDemo`, and then hit the button `Select Folder`. +* In the bottom pane, Click on `Projects`->`Assets`->`Scenes`. Then, **Double-click** on `SimModeSelector`. This will load the SimModeSelector scene into the scene hierarchy pane. *DO NOT* add CarDemo or DroneDemo scene into the scene hierarchy pane. +* Hit the play button to start the simulation (and hit play again to stop the simulation. . +* Alternatively, you can change the SimMode in your `Settings.json` file. (You can read more about [`Settings.json` here](https://github.com/Microsoft/AirSim/blob/master/docs/settings.md)) +* Controlling the car: +Use `WASD` or the `Arrow keys` or the AirSim client. +* Controlling the drone: +Keyboard control is not currently available for drone flight. +* Changing camera views: +Keys `0`, `1`, `2`, `3` are used to toggle windows of different camera views. +* Recording simulation data: +Press *Record* button(Red button) located at the right bottom corner of the screen, to toggle recording of the simulation data. The recorded data can be found at `Documents\AirSim\(Date of recording)` on Windows and `~/Documents/AirSim/(Date of recording)` on Linux. +## Building Custom Environments For AirSim +To use environments other than `UnityDemo`, follow the instructions written [here](custom_unity_environments.md) +## Cross-Compiling to Linux +Unity Editor supports compiling projects to Linux systems. +After following the steps to build AirSim and Unity on Windows, do the following: + +#### Linux Pre-Requisites +Before being able to run Unity Binaries with the Airsim plugin, be sure have airsim and airsim unity built on your linux machine by following the Linux build steps above. + +### Package UnityDemo Binary On Windows + +#### Install Necessary Components +In order to package your project for linux, the **Linux Build Support** Unity add-on must be installed. +* Open **Unity Hub**, and click the **Add component** button in the dropdown window under **more options** to the right of your **Unity 2018.2.15f1** tab. +![Adding components](images/unity_linux_components_1.PNG) +* Make sure the **Linux Build Support** Platform is selected +![Adding components](images/unity_linux_components_2.PNG) +Once this component is successfully installed, you are ready to build Unity Projects for Linux! + +#### Build the Project +* On your Windows machine, build the Unity Demo by navigating to the build settings option in the toolbar ```File -> Build Settings``` +* Make sure the following scenes are set to be built: + 1. SimModeSelector + 2. CarDemo + 3. DroneDemo +* Set the target operating system to linux, and choose the version appropriate for your system (x86 vs x86_64) +* Click ```Build``` +* Transport the built project as well as the generated folder ```"{project_name}_Data"``` to your linux machine + +#### Copy The AirsimWrapper Library to the Project Plugins folder +* On your linux machine, navigate to your AirSim repository, and run the following commands in a terminal window: + ``` + cp Unity/linux-build/libAirsimWrapper.so path/to/your/project/{project_name}_Data/Plugins/{os_version} + ``` +This will generate the necessary shared library to allow Airsim to communicate with Unity and copy it to the plugins folder of your project binary. + +#### Run the Project Binary +* Open a terminal and navigate to your project directory +* Set your project binary as an executable file: +``` +chmod +x "{project_name}.{configuration}" +``` +* Run the binary file +``` +./{project_name}.{configuration} +``` +### Using Airsim API +* For quickstart with the Python APIs for the car or the drone, simply run the [`hello_car.py`](https://github.com/Microsoft/AirSim/blob/master/PythonClient/car/hello_car.py) or the [`hello_drone.py`](https://github.com/Microsoft/AirSim/blob/master/PythonClient/multirotor/hello_drone.py) script accordingly. +* Details of the AirSim C++ and Python APIs are [here](https://github.com/Microsoft/AirSim/blob/master/docs/apis.md). + +### Acknowledgements +* The drone object was provided by user 31415926 on [sketchfab](https://sketchfab.com/models/055841df0fb24cd4abde06a91f7d360a). It is licensed under the [CC License](https://creativecommons.org/licenses/by/4.0/). diff --git a/docs/airsim_ros_pkgs.md b/docs/airsim_ros_pkgs.md new file mode 100644 index 0000000000..56ef7767cc --- /dev/null +++ b/docs/airsim_ros_pkgs.md @@ -0,0 +1,162 @@ +# airsim_ros_pkgs + +A ROS wrapper over the AirSim C++ client library. + +## Setup +- Ubuntu 16.04 + * Install [ROS kinetic](https://wiki.ros.org/kinetic/Installation/Ubuntu) + +- Ubuntu 18.04 + * Install [ROS melodic](https://wiki.ros.org/melodic/Installation/Ubuntu) + +## Build +- Build AirSim +``` +git clone https://github.com/Microsoft/AirSim.git; +cd AirSim; +./setup.sh; +./build.sh; +``` +- Build ROS package + +``` +cd ros; +catkin_make; # or catkin build +``` + +## Running +``` +source devel/setup.bash; +roslaunch airsim_ros_pkgs airsim_node.launch; +roslaunch airsim_ros_pkgs rviz.launch; +``` + +# Using AirSim ROS wrapper +The ROS wrapper is composed of two ROS nodes - the first is a wrapper over AirSim's multirotor C++ client library, and the second is a simple PD position controller. +Let's look at the ROS API for both nodes: + +### AirSim ROS Wrapper Node +#### Publishers: +- `/airsim_node/origin_geo_point` [airsim_ros_pkgs/GPSYaw](https://github.com/microsoft/AirSim/tree/master/ros/src/airsim_ros_pkgs/msg/GPSYaw.msg) +GPS coordinates corresponding to global NED frame. This is set in the airsim's [settings.json](https://microsoft.github.io/AirSim/docs/settings/) file under the `OriginGeopoint` key. + +- `/airsim_node/VEHICLE_NAME/global_gps` [sensor_msgs/NavSatFix](https://docs.ros.org/api/sensor_msgs/html/msg/NavSatFix.html) +This the current GPS coordinates of the drone in airsim. + +- `/airsim_node/VEHICLE_NAME/odom_local_ned` [nav_msgs/Odometry](https://docs.ros.org/api/nav_msgs/html/msg/Odometry.html) +Odometry in NED frame wrt take-off point. + +- `/airsim_node/VEHICLE_NAME/CAMERA_NAME/IMAGE_TYPE/camera_info` [sensor_msgs/CameraInfo](https://docs.ros.org/api/sensor_msgs/html/msg/CameraInfo.html) + +- `/airsim_node/VEHICLE_NAME/CAMERA_NAME/IMAGE_TYPE` [sensor_msgs/Image](https://docs.ros.org/api/sensor_msgs/html/msg/Image.html) + RGB or float image depending on image type requested in settings.json. + +- `/tf` [tf2_msgs/TFMessage](https://docs.ros.org/api/tf2_msgs/html/msg/TFMessage.html) + + +#### Subscribers: +- `/airsim_node/vel_cmd_body_frame` [airsim_ros_pkgs/VelCmd](https://github.com/microsoft/AirSim/tree/master/ros/src/airsim_ros_pkgs/msg/VelCmd.msg) + Ignore `vehicle_name` field, leave it to blank. We will use `vehicle_name` in future for multiple drones. + +- `/airsim_node/vel_cmd_world_frame` [airsim_ros_pkgs/VelCmd](https://github.com/microsoft/AirSim/tree/master/ros/src/airsim_ros_pkgs/msg/VelCmd.msg) + Ignore `vehicle_name` field, leave it to blank. We will use `vehicle_name` in future for multiple drones. + +- `/gimbal_angle_euler_cmd` [airsim_ros_pkgs/GimbalAngleEulerCmd](https://github.com/microsoft/AirSim/tree/master/ros/src/airsim_ros_pkgs/msg/GimbalAngleEulerCmd.msg) + Gimbal set point in euler angles. + +- `/gimbal_angle_quat_cmd` [airsim_ros_pkgs/GimbalAngleQuatCmd](https://github.com/microsoft/AirSim/tree/master/ros/src/airsim_ros_pkgs/msg/GimbalAngleQuatCmd.msg) + Gimbal set point in quaternion. + +#### Services: +- `/airsim_node/VEHICLE_NAME/land` [airsim_ros_pkgs/Takeoff](https://docs.ros.org/api/std_srvs/html/srv/Empty.html) + +- `/airsim_node/takeoff` [airsim_ros_pkgs/Takeoff](https://docs.ros.org/api/std_srvs/html/srv/Empty.html) + +- `/airsim_node/reset` [airsim_ros_pkgs/Reset](https://docs.ros.org/api/std_srvs/html/srv/Empty.html) + Resets *all* drones + +#### Parameters: +- `/airsim_node/update_airsim_control_every_n_sec` [double] + Set in: `$(airsim_ros_pkgs)/launch/airsim_node.launch` + Default: 0.01 seconds. + Timer callback frequency for updating drone odom and state from airsim, and sending in control commands. + The current RPClib interface to unreal engine maxes out at 50 Hz. + Timer callbacks in ROS run at maximum rate possible, so it's best to not touch this parameter. + +- `/airsim_node/update_airsim_img_response_every_n_sec` [double] + Set in: `$(airsim_ros_pkgs)/launch/airsim_node.launch` + Default: 0.01 seconds. + Timer callback frequency for receiving images from all cameras in airsim. + The speed will depend on number of images requested and their resolution. + Timer callbacks in ROS run at maximum rate possible, so it's best to not touch this parameter. + +### Simple PID Position Controller Node + +#### Parameters: +- PD controller parameters: + * `/pd_position_node/kd_x` [double], + `/pd_position_node/kp_y` [double], + `/pd_position_node/kp_z` [double], + `/pd_position_node/kp_yaw` [double] + Proportional gains + + * `/pd_position_node/kd_x` [double], + `/pd_position_node/kd_y` [double], + `/pd_position_node/kd_z` [double], + `/pd_position_node/kd_yaw` [double] + Derivative gains + + * `/pd_position_node/reached_thresh_xyz` [double] + Threshold euler distance (meters) from current position to setpoint position + + * `/pd_position_node/reached_yaw_degrees` [double] + Threshold yaw distance (degrees) from current position to setpoint position + +- `/pd_position_node/update_control_every_n_sec` [double] + Default: 0.01 seconds + +#### Services: +- `/airsim_node/VEHICLE_NAME/gps_goal` [Request: [srv/SetGPSPosition](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_ros_pkgs/srv/SetGPSPosition.srv)] + Target gps position + yaw. + In **absolute** altitude. + +- `/airsim_node/VEHICLE_NAME/local_position_goal` [Request: [srv/SetLocalPosition](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_ros_pkgs/srv/SetLocalPosition.srv) + Target local position + yaw in global NED frame. + +#### Subscribers: +- `/airsim_node/origin_geo_point` [airsim_ros_pkgs/GPSYaw](https://github.com/microsoft/AirSim/tree/master/ros/src/airsim_ros_pkgs/msg/GPSYaw.msg) + Listens to home geo coordinates published by `airsim_node`. + +- `/airsim_node/VEHICLE_NAME/odom_local_ned` [nav_msgs/Odometry](https://docs.ros.org/api/nav_msgs/html/msg/Odometry.html) + Listens to odometry published by `airsim_node` + +#### Publishers: +- `/vel_cmd_world_frame` [airsim_ros_pkgs/VelCmd](airsim_ros_pkgs/VelCmd) + Sends velocity command to `airsim_node` + +### Global params +- Dynamic constraints. These can be changed in `dynamic_constraints.launch`: + * `/max_vel_horz_abs` [double] + Maximum horizontal velocity of the drone (meters/second) + + * `/max_vel_vert_abs` [double] + Maximum vertical velocity of the drone (meters/second) + + * `/max_yaw_rate_degree` [double] + Maximum yaw rate (degrees/second) + +### Misc +#### Windows Subsytem for Linux on Windows 10 +- WSL setup: + * Get [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) + * Get [Ubuntu 16.04](https://www.microsoft.com/en-us/p/ubuntu-1604-lts/9pjn388hp8c9?activetab=pivot:overviewtab) or [Ubuntu 18.04](https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q?activetab=pivot%3Aoverviewtab) + * Go to Ubuntu 16 / 18 instructions! + + +- Setup for X apps (like RViz, rqt_image_view, terminator) in Windows + WSL + * Install [Xming X Server](https://sourceforge.net/projects/xming/). + * Find and run `XLaunch` from the Windows start menu. + Select `Multiple Windows` in first popup, `Start no client` in second popup, **only** `Clipboard` in third popup. Do **not** select `Native Opengl`. + * Open Ubuntu 16.04 / 18.04 session by typing `Ubuntu 16.04` / `Ubuntu 18.04` in Windows start menu. + * Recommended: Install [terminator](http://www.ubuntugeek.com/terminator-multiple-gnome-terminals-in-one-window.html) : `$ sudo apt-get install terminator.` + - You can open terminator in a new window by entering `$ DISPLAY=:0 terminator -u`. diff --git a/docs/airsim_tutorial_pkgs.md b/docs/airsim_tutorial_pkgs.md new file mode 100644 index 0000000000..340983e0ef --- /dev/null +++ b/docs/airsim_tutorial_pkgs.md @@ -0,0 +1,60 @@ +# AirSim ROS Tutorials + +This is a set of sample AirSim `settings.json`s, roslaunch and rviz files to give a starting point for using AirSim with ROS. +See [airsim_ros_pkgs](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_ros_pkgs/README.md) for the ROS API. + + +## Setup +```shell +$ cd PATH_TO/AirSim/ros +$ catkin build airsim_tutorial_pkgs +``` + +## Examples + +### Single drone with monocular and depth cameras, and lidar + - Settings.json - [front_stereo_and_center_mono.json](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_tutorial_pkgs/settings/front_stereo_and_center_mono.json) + ```shell + $ source PATH_TO/AirSim/ros/devel/setup.bash + $ roscd airsim_tutorial_pkgs + $ cp settings/front_stereo_and_center_mono.json ~/Documents/AirSim/settings.json + + ## Start your unreal package or binary here + + $ roslaunch airsim_ros_pkgs airsim_node.launch; + + # in a new pane / terminal + $ roslaunch airsim_tutorial_pkgs front_stereo_and_center_mono.launch + ``` + The above would start rviz with tf's, registered RGBD cloud using [depth_image_proc](https://wiki.ros.org/depth_image_proc) using the [`depth_to_pointcloud` launch file](https://github.com/microsoft/AirSim/master/ros/src/airsim_tutorial_pkgs/launch/front_stereo_and_center_mono/depth_to_pointcloud.launch), and the lidar point cloud. + + +### Two drones, with cameras, lidar, IMU each +- Settings.json - [two_drones_camera_lidar_imu.json](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_tutorial_pkgs/settings/two_drones_camera_lidar_imu.json) + + ```shell + $ source PATH_TO/AirSim/ros/devel/setup.bash + $ roscd airsim_tutorial_pkgs + $ cp settings/two_drones_camera_lidar_imu.json ~/Documents/AirSim/settings.json + + ## Start your unreal package or binary here + + $ roslaunch airsim_ros_pkgs airsim_node.launch; + $ roslaunch airsim_ros_pkgs rviz.launch + ``` +You can view the tfs in rviz. And do a `rostopic list` and `rosservice list` to inspect the services avaiable. + +### Twenty-five drones in a square pattern +- Settings.json - [twenty_five_drones.json](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_tutorial_pkgs/settings/twenty_five_drones.json) + + ```shell + $ source PATH_TO/AirSim/ros/devel/setup.bash + $ roscd airsim_tutorial_pkgs + $ cp settings/twenty_five_drones.json ~/Documents/AirSim/settings.json + + ## Start your unreal package or binary here + + $ roslaunch airsim_ros_pkgs airsim_node.launch; + $ roslaunch airsim_ros_pkgs rviz.launch + ``` +You can view the tfs in rviz. And do a `rostopic list` and `rosservice list` to inspect the services avaiable. diff --git a/docs/apis.md b/docs/apis.md index 5965d542b3..6eae501883 100644 --- a/docs/apis.md +++ b/docs/apis.md @@ -4,7 +4,7 @@ AirSim exposes APIs so you can interact with vehicle in the simulation programmatically. You can use these APIs to retrieve images, get state, control the vehicle and so on. ## Python Quickstart -If you want to use Python to call AirSim APIs, we recommend using Anaconda with Python 3.5 or later versions however some code may also work with Python 2.7 ([help us](../CONTRIBUTING.md) improve compatibility!). +If you want to use Python to call AirSim APIs, we recommend using Anaconda with Python 3.5 or later versions however some code may also work with Python 2.7 ([help us](CONTRIBUTING.md) improve compatibility!). First install this package: diff --git a/docs/build_windows.md b/docs/build_windows.md index 6fba6f5267..f0fb687140 100644 --- a/docs/build_windows.md +++ b/docs/build_windows.md @@ -37,7 +37,7 @@ Once AirSim is set up by following above steps, you can, See [Using APIs](apis.md) and [settings.json](settings.md) for various options available. # AirSim on Unity (Experimental) -[Unity](https://unity3d.com/) is another great game engine platform and we have an [experimental release](https://github.com/Microsoft/AirSim/tree/master/Unity) of AirSim on Unity. Please note that this is work in progress and all features may not work yet. +[Unity](https://unity3d.com/) is another great game engine platform and we have an **experimental** integration of [AirSim with Unity](https://microsoft.github.com/AirSim/Unity). Please note that this is work in progress and all features may not work yet. # FAQ #### I get `error C100 : An internal error has occurred in the compiler` when running build.cmd diff --git a/docs/code_structure.md b/docs/code_structure.md index 0341fda70d..59cd365675 100644 --- a/docs/code_structure.md +++ b/docs/code_structure.md @@ -26,7 +26,7 @@ DroneShell demonstrates how to connect to the simulator using UDP. The simulato ## Contributing -See [Contribution Guidelines](../CONTRIBUTING.md) +See [Contribution Guidelines](CONTRIBUTING.md) ## Unreal Framework diff --git a/docs/create_issue.md b/docs/create_issue.md index 227f81abe1..be29562b0e 100644 --- a/docs/create_issue.md +++ b/docs/create_issue.md @@ -18,6 +18,4 @@ AirSim is open source project and contributors like you keeps it going. It is im * Do not use "Please help" etc in the title. See above. * Do not copy and paste screen shot of error message. Copy and paste text. * Do not use "it doesn't work". Precisely state what is the error message or symptom. -* Do not ask to write code for you. [Contribute](../CONTRIBUTING.md)! - - +* Do not ask to write code for you. [Contribute](CONTRIBUTING.md)! diff --git a/docs/custom_unity_environments.md b/docs/custom_unity_environments.md index 4eb555ee09..22d1eea05b 100644 --- a/docs/custom_unity_environments.md +++ b/docs/custom_unity_environments.md @@ -1,5 +1,5 @@ # Adding AirSim to Custom Unity Projects -Before completing these steps, make sure you have properly [set up AirSim for Unity](../Unity/README.md) +Before completing these steps, make sure you have properly [set up AirSim for Unity](Unity.md) 1. Open the Containing folder of your custom unity project 2. Copy and paste the following items from Unity demo into the main project folder of your custom environment: ``` diff --git a/docs/mavlinkcom.md b/docs/mavlinkcom.md new file mode 100644 index 0000000000..344773f741 --- /dev/null +++ b/docs/mavlinkcom.md @@ -0,0 +1,220 @@ +# Welcome to MavLinkCom + +MavLinkCom is a cross-platform C++ library that helps connect to and communicate with [MavLink](https://github.com/mavlink/mavlink) based vehicles. +Specifically this library is designed to work well with [PX4](https://github.com/PX4/Firmware) based drones. + +## Design + +You can view and edit the [Design.dgml](mavlinkcom_design/Design.dgml) diagram in Visual Studio. +![Overview](mavlinkcom_design/images/overview.png) + +The following are the most important classes in this library. + +### MavLinkNode + +This is the base class for all MavLinkNodes (subclasses include MavLinkVehicle, MavLinkVideoClient and MavLinkVideoServer). +The node connects to your mavlink enabled vehicle via a MavLinkConnection and provides methods for sending MavLinkMessages and MavLinkCommands +and for subscribing to receive messages. This base class also stores the local system id and component id your app wants to use to identify +itself to your remove vehicle. You can also call startHeartbeat to send regular heartbeat messages to keep the connection alive. + +### MavLinkMessage + +This is the encoded MavLinkMessage. For those who have used the mavlink.h C API, this is similar to mavlink_message_t. You do +not create these manually, they are encoded from a strongly typed MavLinkMessageBase subclass. + +### Strongly typed message and command classes + +The MavLinkComGenerator parses the mavlink common.xml message definitions and generates all the MavLink* MavLinkMessageBase subclasses +as well as a bunch of handy mavlink enums and a bunch of strongly typed MavLinkCommand subclasses. + +### MavLinkMessageBase + +This is the base class for a set of strongly typed message classes that are code generated by the MavLinkComGenerator project. +This replaces the C messages defined in the mavlink C API and provides a slightly more object oriented way to send and receive messages +via sendMessage on MavLinkNode. These classes have encode/decode methods that convert to and from the MavLinkMessage class. + +### MavLinkCommand + +This is the base class for a set of strongly typed command classes that are code generated by the MavLinkComGenerator project. +This replaces the C definitions defined in the mavlink C API and provides a more object oriented way to send commands via the sendCommand +method on MavLinkNode. The MavLinkNode takes care of turning these into the underlying mavlink COMMAND_LONG message. + +### MavLinkConnection + +This class provides static helper methods for creating connections to remote MavLink nodes, over serial ports, as well as UDP, or TCP sockets. +This class provides a way to subscribe to receive messages from that node in a pub/sub way so you can have multiple subscribers on the +same connection. MavLinkVehicle uses this to track various messages that define the overall vehicle state. + +### MavLinkVehicle + +MavLinkVehicle is a MavLinkNode that tracks various messages that define the overall vehicle state and provides a VehicleState struct +containing a snapshot of that state, including home position, current orientation, local position, global position, and so on. +This class also provides a bunch of helper methods that wrap commonly used commands providing simple method calls to do things like +arm, disarm, takeoff, land, go to a local coordinate, and fly under offbaord control either by position or velocity control. + +### MavLinkTcpServer + +This helper class provides a way to setup a "server" that accepts MavLinkConnections from remote nodes. You can use this class +to get a connection that you can then give to MavLinkVideoServer to serve images over MavLink. + +### MavLinkFtpClient + +This helper class takes a given MavLinkConnection and provides FTP client support for the MAVLINK_MSG_ID_FILE_TRANSFER_PROTOCOL +for vehicles that support the FTP capability. This class provides simple methods to list directory contents, and the get and put +files. + +### MavLinkVideoClient + +This helper class takes a given MavLinkConnection and provides helper methods for requesting video from remote node and +packaging up the MAVLINK_MSG_ID_DATA_TRANSMISSION_HANDSHAKE and MAVLINK_MSG_ID_ENCAPSULATED_DATA messages into simple to use +MavLinkVideoFrames. + +### MavLinkVideoServer + +This helper class takes a given MavLinkConnection and provides the server side of the MavLinkVideoClient protocol, including helper methods +for notifying when there is a video request to process (hasVideoRequest) and a method to send video frames (sendFrame) which +will generate the right MAVLINK_MSG_ID_DATA_TRANSMISSION_HANDSHAKE and MAVLINK_MSG_ID_ENCAPSULATED_DATA sequence. + +## Examples + +The following code from the UnitTest project shows how to connect to a [Pixhawk](http://www.pixhawk.org/) flight controller over USB serial port, +then wait for the first heartbeat message to be received: + + auto connection = MavLinkConnection::connectSerial("drone", "/dev/ttyACM0", 115200, "sh /etc/init.d/rc.usb\n"); + MavLinkHeartbeat heartbeat; + if (!waitForHeartbeat(10000, heartbeat)) { + throw std::runtime_error("Received no heartbeat from PX4 after 10 seconds"); + } + + +The following code connects to serial port, and then forwards all messages to and from QGroundControl to that drone using another connection +that is joined to the drone stream. + + auto droneConnection = MavLinkConnection::connectSerial("drone", "/dev/ttyACM0", 115200, "sh /etc/init.d/rc.usb\n"); + auto proxyConnection = MavLinkConnection::connectRemoteUdp("qgc", "127.0.0.1", "127.0.0.1", 14550); + droneConnection->join(proxyConnection); + +The following code then takes that connection and turns on heartBeats and starts tracking vehicle information using local +system id 166 and component id 1. + + auto vehicle = std::make_shared(166, 1); + vehicle->connect(connection); + vehicle->startHeartbeat(); + + std::this_thread::sleep_for(std::chrono::seconds(5)); + + VehicleState state = vehicle->getVehicleState(); + printf("Home position is %s, %f,%f,%f\n", state.home.is_set ? "set" : "not set", + state.home.global_pos.lat, state.home.global_pos.lon, state.home.global_pos.alt); + +The following code uses the vehicle object to arm the drone and take off and wait for the takeoff altitude to be reached: + + bool rc = false; + if (!vehicle->armDisarm(true).wait(3000, &rc) || !rc) { + printf("arm command failed\n"); + return; + } + if (!vehicle->takeoff(targetAlt).wait(3000, &rc) || !rc) { + printf("takeoff command failed\n"); + return; + } + int version = vehicle->getVehicleStateVersion(); + while (true) { + int newVersion = vehicle->getVehicleStateVersion(); + if (version != newVersion) { + VehicleState state = vehicle->getVehicleState(); + float alt = state.local_est.pos.z; + if (alt >= targetAlt - delta && alt <= targetAlt + delta) + { + reached = true; + printf("Target altitude reached\n"); + break; + } + } else { + std::this_thread::sleep_for(std::chrono::milliseconds(10)); + } + } + +The following code uses offboard control to make the drone fly in a circle with camera pointed at the center. +Here we use the subscribe method to check each new local position message to indicate so we can compute the new +velocity vector as soon as that new position is received. We request a high rate for those messages using +setMessageInterval to ensure smooth circular orbit. + + vehicle->setMessageInterval((int)MavLinkMessageIds::MAVLINK_MSG_ID_LOCAL_POSITION_NED, 30); + vehicle->requestControl(); + int subscription = vehicle->getConnection()->subscribe( + [&](std::shared_ptr connection, const MavLinkMessage& m) { + if (m.msgid == (int)MavLinkMessageIds::MAVLINK_MSG_ID_LOCAL_POSITION_NED) + { + float x = localPos.x; + float y = localPos.y; + float dx = x - cx; + float dy = y - cy; + float angle = atan2(dy, dx); + if (angle < 0) angle += M_PI * 2; + float tangent = angle + M_PI_2; + double newvx = orbitSpeed * cos(tangent); + double newvy = orbitSpeed * sin(tangent); + float heading = angle + M_PI; + vehicle->moveByLocalVelocityWithAltHold(newvx, newvy, altitude, true, heading); + } + }); + +The following code stops flying the drone in offboard mode and tells the drone to loiter at its current location. +This version of the code shows how to use the AsyncResult without blocking on a wait call. + + vehicle->releaseControl(); + if (vehicle->loiter().then([=](bool rc) { + printf("loiter command %s\n", rc ? "succeeded" : "failed"); + } + +The following code gets all configurable parameters from the drone and prints them: + + auto list = vehicle->getParamList(); + auto end = list.end(); + int count = 0; + for (auto iter = list.begin(); iter < end; iter++) + { + count++; + MavLinkParameter p = *iter; + if (p.type == MAV_PARAM_TYPE_REAL32 || p.type == MAV_PARAM_TYPE_REAL64) { + printf("%s=%f\n", p.name.c_str(), p.value); + } + else { + printf("%s=%d\n", p.name.c_str(), static_cast(p.value)); + } + } + +The following code sets a parameter on the Pixhawk to disable the USB safety check (this is handy if you are controlling +the Pixhawk over USB using another onboard computer that is part of the drone itself). You should NOT do this if you +are connecting your PC or laptop to the drone over USB. + + MavLinkParameter p; + p.name = "CBRK_USB_CHK"; + p.value = 197848; + if (!vehicle->setParameter(p).wait(3000,&rc) || !rc) { + printf("Setting the CBRK_USB_CHK failed"); + } + +MavLinkVehicle actually has a helper method for this called allowFlightControlOverUsb, so now you know how it is implemented :-) + +## Advanced Connections + +You can wire up different configurations of mavlink pipelines using the MavLinkConnection class "join" method as shown below. + +Example 1, we connect to PX4 over serial, and proxy those messages through to QGroundControl and the LogViewer who are listening on remote ports. + +![Serial to QGC](mavlinkcom_design/images/example1.png) + +Example 2: simulation can talk to jMavSim and jMavSim connects to PX4. jMavSim can also manage multiple connections, so it can talk to unreal simulator. +Another MavLinkConnection can be joined to proxy connections that jMavSim doesn't support, like the LogViewer or a remote camera node. + +![Serial to QGC](mavlinkcom_design/images/example2.png) + +Example 3: we use MavLinkConnection to connect to PX4 over serial, then join additional connections for all our remote nodes including jMavSim. + +![Serial to QGC](mavlinkcom_design/images/example3.png) + +Example 4: We can also do distributed systems to control the drone remotely: + +![Serial to QGC](mavlinkcom_design/images/example4.png) diff --git a/MavLinkCom/Design/Design.dgml b/docs/mavlinkcom_design/Design.dgml similarity index 100% rename from MavLinkCom/Design/Design.dgml rename to docs/mavlinkcom_design/Design.dgml diff --git a/MavLinkCom/Design/FtpDesign.dgml b/docs/mavlinkcom_design/FtpDesign.dgml similarity index 100% rename from MavLinkCom/Design/FtpDesign.dgml rename to docs/mavlinkcom_design/FtpDesign.dgml diff --git a/MavLinkCom/Design/OffboardControl.dgml b/docs/mavlinkcom_design/OffboardControl.dgml similarity index 100% rename from MavLinkCom/Design/OffboardControl.dgml rename to docs/mavlinkcom_design/OffboardControl.dgml diff --git a/MavLinkCom/Design/images/example1.png b/docs/mavlinkcom_design/images/example1.png similarity index 100% rename from MavLinkCom/Design/images/example1.png rename to docs/mavlinkcom_design/images/example1.png diff --git a/MavLinkCom/Design/images/example2.png b/docs/mavlinkcom_design/images/example2.png similarity index 100% rename from MavLinkCom/Design/images/example2.png rename to docs/mavlinkcom_design/images/example2.png diff --git a/MavLinkCom/Design/images/example3.png b/docs/mavlinkcom_design/images/example3.png similarity index 100% rename from MavLinkCom/Design/images/example3.png rename to docs/mavlinkcom_design/images/example3.png diff --git a/MavLinkCom/Design/images/example4.png b/docs/mavlinkcom_design/images/example4.png similarity index 100% rename from MavLinkCom/Design/images/example4.png rename to docs/mavlinkcom_design/images/example4.png diff --git a/MavLinkCom/Design/images/overview.png b/docs/mavlinkcom_design/images/overview.png similarity index 100% rename from MavLinkCom/Design/images/overview.png rename to docs/mavlinkcom_design/images/overview.png diff --git a/docs/mavlinkcom_mocap.md b/docs/mavlinkcom_mocap.md new file mode 100644 index 0000000000..2d49a9baa3 --- /dev/null +++ b/docs/mavlinkcom_mocap.md @@ -0,0 +1,28 @@ +# Welcome to MavLinkMoCap + +This folder contains the MavLinkMoCap library which connects to a OptiTrack camera system +for accurate indoor location. + +## Dependencies: +* [OptiTrack Motive](http://www.optitrack.com/products/motive/). +* [MavLinkCom](mavlinkcom.md). + +### Setup RigidBody + +First you need to define a RigidBody named 'Quadrocopter' using Motive. +See [Rigid_Body_Tracking](http://wiki.optitrack.com/index.php?title=Rigid_Body_Tracking). + +### MavLinkTest + +Use MavLinkTest to talk to your PX4 drone, with "-server:addr:port", for example, when connected +to drone wifi use: + + MavLinkMoCap -server:10.42.0.228:14590 "-project:D:\OptiTrack\Motive Project 2016-12-19 04.09.42 PM.ttp" + +This publishes the ATT_POS_MOCAP messages and you can proxy those through to the PX4 by running +MavLinkTest on the dronebrain using: + + MavLinkTest -serial:/dev/ttyACM0,115200 -proxy:10.42.0.228:14590 + +Now the drone will get the ATT_POS_MOCAP and you should see the light turn green meaning it is +now has a home position and is ready to fly. \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml deleted file mode 100644 index ba5f32156a..0000000000 --- a/docs/mkdocs.yml +++ /dev/null @@ -1,181 +0,0 @@ -dev_addr: 127.0.0.1:8080 -strict: true -site_name: AirSim -site_dir: build -docs_dir: doc_root -repo_url: https://github.com/microsoft/airsim -#site_url: http://microsoft.github.io/airsim -#edit_uri: edit/master/docs -#repo_name: GitHub -site_description: 'Open source simulator based on Unreal Engine for autonomous vehicles from Microsoft AI & Research' - -markdown_extensions: - # - meta - # - toc: - # permalink: true # For ¶ - # #permalink: "#" - # #separator: "_" - # - admonition - # - fenced_code - # - codehilite - # - smarty - # - tables - # - def_list - # - sane_lists - # - codehilite: - # guess_lang: true - # linenums: true - # - mdx_math: - # enable_dollar_delimiter: True - # - pymdownx.highlight: - # guess_lang: true - # extend_pygments_lang: - # - name: php - # lang: php - # options: - # startinline: true - # - pymdownx.arithmatex: - # #inline_syntax: ['dollar'] - # #block_syntax: ['dollar', 'begin'] - # #insert_as_script: True - # # - pymdownx.keys: - # # strict: false - # - pymdownx.betterem: - # smart_enable: all - # - pymdownx.caret - # #- pymdownx.critic - # - pymdownx.details - # - pymdownx.inlinehilite - # - pymdownx.tasklist: - # custom_checkbox: true - # #- pymdownx.magiclink: - # #- base_repo_url: https://github.com/abinit/abinit - # #- repo_url_shortener: true - # - pymdownx.mark - # - pymdownx.smartsymbols: - # registered: false - # copyright: false - # care_of: false - # - pymdownx.superfences - # - pymdownx.tilde - -remote_branch: gh-pages -#remote_name: origin - -theme: - #name: 'rtd-dropdown' - name: 'readthedocs' - # Disable the default top left logo until we sort out our custom one. - logo: - icon: ' ' -# extra_css: -# - css/extra.css -# - css/gallery.css -# - css/my_codehilite.css - - # # Don't include MkDocs' JavaScript - # include_search_page: false - # search_index_only: true - -extra: - version: 1.2.1 - #previous_published_versions: [1.2.1] - #logo: images/logo-abinit-2015.svg - feature: - tabs: true - palette: - #primary: orange - #accent: orange - # primary: deep orange - # accent: deep orange - #primary: indigo - #accent: indigo - #font: - #fonttext: 'Ubuntu' - #fontcode: 'Ubuntu Mono' - social: - - type: facebook - link: https://www.facebook.com/groups/1225832467530667/ - - type: github-alt - link: https://github.com/Microsoft/AirSim - # - type: twitter - # link: https://twitter.com/hashtag/abinit - # - type: youtube - # link: https://www.youtube.com/watch?v=gcbfb_Mteo4 - -copyright: Copyright © 2018 Microsoft Research - -nav: - - "Home": 'README.md' - - "Whats New": 'CHANGELOG.md' - - "Get AirSim": - - "Download Binaries": 'docs/use_precompiled.md' - - "Build on Windows": 'docs/build_windows.md' - - "Build on Linux": 'docs/build_linux.md' - - "Creating Custom Environment": 'docs/unreal_custenv.md' - - "Using AirSim": - - "Core APIs": 'docs/apis.md' - - "Image APIs": 'docs/image_apis.md' - - "C++ APIs": 'docs/apis_cpp.md' - - "Development Workflow": 'docs/dev_workflow.md' - - "Settings": 'docs/settings.md' - - "Camera Views": 'docs/camera_views.md' - - "Using Car": 'docs/using_car.md' - - "Remote Control": 'docs/remote_control.md' - - "XBox Controller": 'docs/xbox_controller.md' - - "Steering Wheel": 'docs/steering_wheel_installation.md' - - "Multiple Vehicles": 'docs/multi_vehicle.md' - - "Sensors": 'docs/sensors.md' - - "LIDAR": 'docs/lidar.md' - - "ROS": 'docs/ros.md' - - "Playing Logs": 'docs/playback.md' - - "Design": - - "Architecture": 'docs/design.md' - - "Code Structure": 'docs/code_structure.md' - - "Coding Guidelines": 'docs/coding_guidelines.md' - - "Flight Controller": 'docs/flight_controller.md' - - "Simple Flight": 'docs/simple_flight.md' - - "Hello Drone": 'docs/hello_drone.md' - - "MavLink and PX4": - - "PX4 Setup for AirSim": 'docs/px4_setup.md' - - "PX4 in SITL": 'docs/px4_sitl.md' - - "AirSim with Pixhawk": 'https://youtu.be/1oY8Qu5maQQ' - - "PX4 Setup with AirSim": 'https://youtu.be/HNWdYrtw3f0' - - "Debugging Attitude Estimation": 'https://www.youtube.com/watch?v=d_FyjKDWQfc&feature=youtu.be' - - "Intercepting MavLink Messages": 'https://github.com/Microsoft/AirSim/wiki/Intercepting-MavLink-messages' - - "Rapid Descent on PX4 Drones": 'https://github.com/Microsoft/AirSim/wiki/Rapid-Descent-on-PX4-drones' - - "Building PX4": "docs/px4_build.md" - - "PX4/MavLink Logging": 'docs/px4_logging.md' - - "MavLink LogViewer": "docs/log_viewer.md" - # - "MavLinkCom": 'MavLinkCom/README.md' - # - "MavLink MoCap": 'MavLinkCom/MavLinkMoCap/Readme.md' - - "Upgrading": - - "Upgrading Unreal": 'docs/unreal_upgrade.md' - - "Upgrading APIs": 'docs/upgrade_apis.md' - - "Upgrading Settings": 'docs/upgrade_settings.md' - - "Contributed Tutorials": - - "Reinforcement Learning": 'docs/reinforcement_learning.md' - - "Using Environments from Marketplace": 'https://www.youtube.com/watch?v=y09VbdQWvQY' - - "Simple Collision Avoidance": 'https://github.com/simondlevy/AirSimTensorFlow' - - "Autonomous Driving on Azure": 'https://aka.ms/AutonomousDrivingCookbook' - - "Building Hexacopter": 'https://github.com/Microsoft/AirSim/wiki/hexacopter' - - "Moving on Path Demo": 'https://github.com/Microsoft/AirSim/wiki/moveOnPath-demo' - - "Building Point Clouds": 'https://github.com/Microsoft/AirSim/wiki/Point-Clouds' - - "Surveying Using Drone": 'https://github.com/Microsoft/AirSim/wiki/Implementing-a-Drone-Survey-script' - - "Misc": - - "AirSim on Real Drones": 'docs/custom_drone.md' - - "Installing cmake on Linux": 'docs/cmake_linux.md' - - "Tips for Busy HDD": 'docs/hard_drive.md' - - "pfm format": 'docs/pfm.md' - - "Setting up Unreal Environment": 'docs/unreal_proj.md' - - "Blocks Environment": 'docs/unreal_blocks.md' - - "Who is Using AirSim": 'docs/who_is_using.md' - - "Working with UE Plugin Contents": 'docs/working_with_plugin_contents.md' - - "Formula Student Technion Self-drive": 'https://github.com/Microsoft/AirSim/wiki/technion' - - "Support": - - "FAQ": 'docs/faq.md' - - "Support": 'SUPPORT.md' - - "Create Issue": 'docs/create_issue.md' - - "Contribute": 'CONTRIBUTING.md' - - diff --git a/docs/python.md b/docs/python.md deleted file mode 100644 index caf1354e01..0000000000 --- a/docs/python.md +++ /dev/null @@ -1,3 +0,0 @@ -# Using Python APIs for AirSim - -This document is now merged with [general APIs document](apis.md). \ No newline at end of file diff --git a/docs/use_precompiled.md b/docs/use_precompiled.md index c477327eff..76694067bb 100644 --- a/docs/use_precompiled.md +++ b/docs/use_precompiled.md @@ -12,7 +12,7 @@ You can simply download precompiled binaries and run to get started immediately. A free environment called Windridge City is available at [Unity Asset Store](https://assetstore.unity.com/) as an experimental release of AirSim on Unity. **Note**: This is an old release, and many of the features and APIs might not work. ## Controlling Vehicles -Most of our users typically use [APIs](apis.md) to control the vehicles. However if you can also control vehicles manually. You can drive the car using keyboard, gamepad or [steering wheel](steering_wheel_installation.md). To fly drone manually, you will need either XBox controller or a remote control (feel free to [contribute](../CONTRIBUTING.md) keyboard support). Please see [remote control setup](remote_control.md) for more details. Alternatively you can use [APIs](apis.md) for programmatic control or use so-called [Computer Vision mode](image_apis.md) to move around in environment using the keyboard. +Most of our users typically use [APIs](apis.md) to control the vehicles. However if you can also control vehicles manually. You can drive the car using keyboard, gamepad or [steering wheel](steering_wheel_installation.md). To fly drone manually, you will need either XBox controller or a remote control (feel free to [contribute](CONTRIBUTING.md) keyboard support). Please see [remote control setup](remote_control.md) for more details. Alternatively you can use [APIs](apis.md) for programmatic control or use so-called [Computer Vision mode](image_apis.md) to move around in environment using the keyboard. ## Don't Have Good GPU? The AirSim binaries, like CityEnviron, requires a beefy GPU to run smoothly. You can run them in low resolution mode by editing the `run.bat` file on Windows like this: diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..102062c4a3 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,115 @@ +site_name: AirSim +site_dir: build +repo_url: https://github.com/microsoft/airsim +#site_url: http://microsoft.github.io/airsim +#edit_uri: edit/master/docs +#repo_name: GitHub +site_description: 'Open source simulator based on Unreal Engine for autonomous vehicles from Microsoft AI & Research' +# docs_dir: '/home/madratman/projects/AirSim_upstream/AirSim' + +markdown_extensions: + - toc: + permalink: "#" + +remote_branch: gh-pages + +theme: + name: 'readthedocs' + logo: + icon: ' ' + +extra: + highlightjs: true + version: 1.2.1 + feature: + tabs: true + palette: + social: + - type: facebook + link: https://www.facebook.com/groups/1225832467530667/ + - type: github-alt + link: https://github.com/Microsoft/AirSim + +copyright: Copyright © 2018 Microsoft Research + +nav: + - "Home": + - "Home": 'README.md' + - "Changelog": 'CHANGELOG.md' + - "Get AirSim": + - "Download Binaries": 'use_precompiled.md' + - "Build on Windows": 'build_windows.md' + - "Build on Linux": 'build_linux.md' + - "Docker on Linux": 'docker_ubuntu.md' + - "Custom Unreal Environment": 'unreal_custenv.md' + - "AirSim with Unity": "Unity.md" + - "Custom Unity Environment": "custom_unity_environments.md" + - "Unity APIs": "unity_api_support.md" + - "Using AirSim": + - "Core APIs": 'apis.md' + - "Image APIs": 'image_apis.md' + - "C++ APIs": 'apis_cpp.md' + - "Development Workflow": 'dev_workflow.md' + - "Settings": 'settings.md' + - "Camera Views": 'camera_views.md' + - "Car Mode": 'using_car.md' + - "Remote Control": 'remote_control.md' + - "XBox Controller": 'xbox_controller.md' + - "Steering Wheel": 'steering_wheel_installation.md' + - "Multiple Vehicles": 'multi_vehicle.md' + - "Sensors": 'sensors.md' + - "LIDAR": 'lidar.md' + - "Infrared Camera": "InfraredCamera.md" + - "ROS: AirSim ROS Wrapper": "airsim_ros_pkgs.md" + - "ROS: AirSim Tutorial Packages": "airsim_tutorial_pkgs.md" + - "Domain Randomization": "retexturing.md" + - "Mesh Vertex Buffers": "meshes.md" + - "Playing Logs": 'playback.md' + - "Design": + - "Architecture": 'design.md' + - "Code Structure": 'code_structure.md' + - "Coding Guidelines": 'coding_guidelines.md' + - "Flight Controller": 'flight_controller.md' + - "Simple Flight": 'simple_flight.md' + - "Hello Drone": 'hello_drone.md' + - "MavLink and PX4": + - "PX4 Setup for AirSim": 'px4_setup.md' + - "PX4 in SITL": 'px4_sitl.md' + - "AirSim with Pixhawk": 'https://youtu.be/1oY8Qu5maQQ' + - "PX4 Setup with AirSim": 'https://youtu.be/HNWdYrtw3f0' + - "Debugging Attitude Estimation": 'https://www.youtube.com/watch?v=d_FyjKDWQfc&feature=youtu.be' + - "Intercepting MavLink Messages": 'https://github.com/Microsoft/AirSim/wiki/Intercepting-MavLink-messages' + - "Rapid Descent on PX4 Drones": 'https://github.com/Microsoft/AirSim/wiki/Rapid-Descent-on-PX4-drones' + - "Building PX4": "px4_build.md" + - "PX4/MavLink Logging": 'px4_logging.md' + - "MavLink LogViewer": "log_viewer.md" + - "MavLinkCom": 'mavlinkcom.md' + - "MavLink MoCap": 'mavlinkcom_mocap.md' + - "Upgrading": + - "Upgrading Unreal": 'unreal_upgrade.md' + - "Upgrading APIs": 'upgrade_apis.md' + - "Upgrading Settings": 'upgrade_settings.md' + - "Contributed Tutorials": + - "Reinforcement Learning": 'reinforcement_learning.md' + - "Using Environments from Marketplace": 'https://www.youtube.com/watch?v=y09VbdQWvQY' + - "Simple Collision Avoidance": 'https://github.com/simondlevy/AirSimTensorFlow' + - "Autonomous Driving on Azure": 'https://aka.ms/AutonomousDrivingCookbook' + - "Building Hexacopter": 'https://github.com/Microsoft/AirSim/wiki/hexacopter' + - "Moving on Path Demo": 'https://github.com/Microsoft/AirSim/wiki/moveOnPath-demo' + - "Building Point Clouds": 'https://github.com/Microsoft/AirSim/wiki/Point-Clouds' + - "Surveying Using Drone": 'https://github.com/Microsoft/AirSim/wiki/Implementing-a-Drone-Survey-script' + - "Misc": + - "AirSim on Real Drones": 'custom_drone.md' + - "Installing cmake on Linux": 'cmake_linux.md' + - "Tips for Busy HDD": 'hard_drive.md' + - "pfm format": 'pfm.md' + - "Setting up Unreal Environment": 'unreal_proj.md' + - "Blocks Environment": 'unreal_blocks.md' + - "Who is Using AirSim": 'who_is_using.md' + - "Working with UE Plugin Contents": 'working_with_plugin_contents.md' + - "Formula Student Technion Self-drive": 'https://github.com/Microsoft/AirSim/wiki/technion' + - "Support": + - "FAQ": 'faq.md' + - "Support": 'SUPPORT.md' + - "Create Issue": 'create_issue.md' + - "Contribute": 'CONTRIBUTING.md' \ No newline at end of file diff --git a/ros/src/airsim_ros_pkgs/README.md b/ros/src/airsim_ros_pkgs/README.md index 5bcc9d94c0..9edb213962 100644 --- a/ros/src/airsim_ros_pkgs/README.md +++ b/ros/src/airsim_ros_pkgs/README.md @@ -1,162 +1,3 @@ # airsim_ros_pkgs -A ROS wrapper over the AirSim C++ client library. - -## Setup -- Ubuntu 16.04 - * Install [ROS kinetic](https://wiki.ros.org/kinetic/Installation/Ubuntu) - -- Ubuntu 18.04 - * Install [ROS melodic](https://wiki.ros.org/melodic/Installation/Ubuntu) - -## Build -- Build AirSim -``` -git clone https://github.com/Microsoft/AirSim.git; -cd AirSim; -./setup.sh; -./build.sh; -``` -- Build ROS package - -``` -cd ros; -catkin_make; # or catkin build -``` - -## Running -``` -source devel/setup.bash; -roslaunch airsim_ros_pkgs airsim_node.launch; -roslaunch airsim_ros_pkgs rviz.launch; -``` - -# Using AirSim ROS wrapper -The ROS wrapper is composed of two ROS nodes - the first is a wrapper over AirSim's multirotor C++ client library, and the second is a simple PD position controller. -Let's look at the ROS API for both nodes: - -### AirSim ROS Wrapper Node -#### Publishers: -- `/airsim_node/origin_geo_point` [airsim_ros_pkgs/GPSYaw](msg/GPSYaw.msg) -GPS coordinates corresponding to global NED frame. This is set in the airsim's [settings.json](https://microsoft.github.io/AirSim/docs/settings/) file under the `OriginGeopoint` key. - -- `/airsim_node/VEHICLE_NAME/global_gps` [sensor_msgs/NavSatFix](https://docs.ros.org/api/sensor_msgs/html/msg/NavSatFix.html) -This the current GPS coordinates of the drone in airsim. - -- `/airsim_node/VEHICLE_NAME/odom_local_ned` [nav_msgs/Odometry](https://docs.ros.org/api/nav_msgs/html/msg/Odometry.html) -Odometry in NED frame wrt take-off point. - -- `/airsim_node/VEHICLE_NAME/CAMERA_NAME/IMAGE_TYPE/camera_info` [sensor_msgs/CameraInfo](https://docs.ros.org/api/sensor_msgs/html/msg/CameraInfo.html) - -- `/airsim_node/VEHICLE_NAME/CAMERA_NAME/IMAGE_TYPE` [sensor_msgs/Image](https://docs.ros.org/api/sensor_msgs/html/msg/Image.html) - RGB or float image depending on image type requested in settings.json. - -- `/tf` [tf2_msgs/TFMessage](https://docs.ros.org/api/tf2_msgs/html/msg/TFMessage.html) - - -#### Subscribers: -- `/airsim_node/vel_cmd_body_frame` [airsim_ros_pkgs/VelCmd](msg/VelCmd.msg) - Ignore `vehicle_name` field, leave it to blank. We will use `vehicle_name` in future for multiple drones. - -- `/airsim_node/vel_cmd_world_frame` [airsim_ros_pkgs/VelCmd](msg/VelCmd.msg) - Ignore `vehicle_name` field, leave it to blank. We will use `vehicle_name` in future for multiple drones. - -- `/gimbal_angle_euler_cmd` [airsim_ros_pkgs/GimbalAngleEulerCmd](msg/GimbalAngleEulerCmd.msg) - Gimbal set point in euler angles. - -- `/gimbal_angle_quat_cmd` [airsim_ros_pkgs/GimbalAngleQuatCmd](msg/GimbalAngleQuatCmd.msg) - Gimbal set point in quaternion. - -#### Services: -- `/airsim_node/VEHICLE_NAME/land` [airsim_ros_pkgs/Takeoff](https://docs.ros.org/api/std_srvs/html/srv/Empty.html) - -- `/airsim_node/takeoff` [airsim_ros_pkgs/Takeoff](https://docs.ros.org/api/std_srvs/html/srv/Empty.html) - -- `/airsim_node/reset` [airsim_ros_pkgs/Reset](https://docs.ros.org/api/std_srvs/html/srv/Empty.html) - Resets *all* drones - -#### Parameters: -- `/airsim_node/update_airsim_control_every_n_sec` [double] - Set in: `$(airsim_ros_pkgs)/launch/airsim_node.launch` - Default: 0.01 seconds. - Timer callback frequency for updating drone odom and state from airsim, and sending in control commands. - The current RPClib interface to unreal engine maxes out at 50 Hz. - Timer callbacks in ROS run at maximum rate possible, so it's best to not touch this parameter. - -- `/airsim_node/update_airsim_img_response_every_n_sec` [double] - Set in: `$(airsim_ros_pkgs)/launch/airsim_node.launch` - Default: 0.01 seconds. - Timer callback frequency for receiving images from all cameras in airsim. - The speed will depend on number of images requested and their resolution. - Timer callbacks in ROS run at maximum rate possible, so it's best to not touch this parameter. - -### Simple PID Position Controller Node - -#### Parameters: -- PD controller parameters: - * `/pd_position_node/kd_x` [double], - `/pd_position_node/kp_y` [double], - `/pd_position_node/kp_z` [double], - `/pd_position_node/kp_yaw` [double] - Proportional gains - - * `/pd_position_node/kd_x` [double], - `/pd_position_node/kd_y` [double], - `/pd_position_node/kd_z` [double], - `/pd_position_node/kd_yaw` [double] - Derivative gains - - * `/pd_position_node/reached_thresh_xyz` [double] - Threshold euler distance (meters) from current position to setpoint position - - * `/pd_position_node/reached_yaw_degrees` [double] - Threshold yaw distance (degrees) from current position to setpoint position - -- `/pd_position_node/update_control_every_n_sec` [double] - Default: 0.01 seconds - -#### Services: -- `/airsim_node/VEHICLE_NAME/gps_goal` [Request: [msgs/airsim_ros_pkgs/GPSYaw](msgs/airsim_ros_pkgs/GPSYaw)] - Target gps position + yaw. - In **absolute** altitude. - -- `/airsim_node/VEHICLE_NAME/local_position_goal` [Request: [msgs/airsim_ros_pkgs/XYZYaw](msgs/airsim_ros_pkgs/XYZYaw) - Target local position + yaw in global NED frame. - -#### Subscribers: -- `/airsim_node/origin_geo_point` [airsim_ros_pkgs/GPSYaw](msg/GPSYaw.msg) - Listens to home geo coordinates published by `airsim_node`. - -- `/airsim_node/VEHICLE_NAME/odom_local_ned` [nav_msgs/Odometry](https://docs.ros.org/api/nav_msgs/html/msg/Odometry.html) - Listens to odometry published by `airsim_node` - -#### Publishers: -- `/vel_cmd_world_frame` [airsim_ros_pkgs/VelCmd](airsim_ros_pkgs/VelCmd) - Sends velocity command to `airsim_node` - -### Global params -- Dynamic constraints. These can be changed in `dynamic_constraints.launch`: - * `/max_vel_horz_abs` [double] - Maximum horizontal velocity of the drone (meters/second) - - * `/max_vel_vert_abs` [double] - Maximum vertical velocity of the drone (meters/second) - - * `/max_yaw_rate_degree` [double] - Maximum yaw rate (degrees/second) - -### Misc -#### Windows Subsytem for Linux on Windows 10 -- WSL setup: - * Get [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) - * Get [Ubuntu 16.04](https://www.microsoft.com/en-us/p/ubuntu-1604-lts/9pjn388hp8c9?activetab=pivot:overviewtab) or [Ubuntu 18.04](https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q?activetab=pivot%3Aoverviewtab) - * Go to Ubuntu 16 / 18 instructions! - - -- Setup for X apps (like RViz, rqt_image_view, terminator) in Windows + WSL - * Install [Xming X Server](https://sourceforge.net/projects/xming/). - * Find and run `XLaunch` from the Windows start menu. - Select `Multiple Windows` in first popup, `Start no client` in second popup, **only** `Clipboard` in third popup. Do **not** select `Native Opengl`. - * Open Ubuntu 16.04 / 18.04 session by typing `Ubuntu 16.04` / `Ubuntu 18.04` in Windows start menu. - * Recommended: Install [terminator](http://www.ubuntugeek.com/terminator-multiple-gnome-terminals-in-one-window.html) : `$ sudo apt-get install terminator.` - - You can open terminator in a new window by entering `$ DISPLAY=:0 terminator -u`. +This page has moved [here](https://github.com/microsoft/AirSim/blob/master/docs/airsim_ros_pkgs.md). \ No newline at end of file diff --git a/ros/src/airsim_tutorial_pkgs/README.md b/ros/src/airsim_tutorial_pkgs/README.md index 340983e0ef..e7a07ea8d1 100644 --- a/ros/src/airsim_tutorial_pkgs/README.md +++ b/ros/src/airsim_tutorial_pkgs/README.md @@ -1,60 +1,3 @@ # AirSim ROS Tutorials -This is a set of sample AirSim `settings.json`s, roslaunch and rviz files to give a starting point for using AirSim with ROS. -See [airsim_ros_pkgs](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_ros_pkgs/README.md) for the ROS API. - - -## Setup -```shell -$ cd PATH_TO/AirSim/ros -$ catkin build airsim_tutorial_pkgs -``` - -## Examples - -### Single drone with monocular and depth cameras, and lidar - - Settings.json - [front_stereo_and_center_mono.json](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_tutorial_pkgs/settings/front_stereo_and_center_mono.json) - ```shell - $ source PATH_TO/AirSim/ros/devel/setup.bash - $ roscd airsim_tutorial_pkgs - $ cp settings/front_stereo_and_center_mono.json ~/Documents/AirSim/settings.json - - ## Start your unreal package or binary here - - $ roslaunch airsim_ros_pkgs airsim_node.launch; - - # in a new pane / terminal - $ roslaunch airsim_tutorial_pkgs front_stereo_and_center_mono.launch - ``` - The above would start rviz with tf's, registered RGBD cloud using [depth_image_proc](https://wiki.ros.org/depth_image_proc) using the [`depth_to_pointcloud` launch file](https://github.com/microsoft/AirSim/master/ros/src/airsim_tutorial_pkgs/launch/front_stereo_and_center_mono/depth_to_pointcloud.launch), and the lidar point cloud. - - -### Two drones, with cameras, lidar, IMU each -- Settings.json - [two_drones_camera_lidar_imu.json](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_tutorial_pkgs/settings/two_drones_camera_lidar_imu.json) - - ```shell - $ source PATH_TO/AirSim/ros/devel/setup.bash - $ roscd airsim_tutorial_pkgs - $ cp settings/two_drones_camera_lidar_imu.json ~/Documents/AirSim/settings.json - - ## Start your unreal package or binary here - - $ roslaunch airsim_ros_pkgs airsim_node.launch; - $ roslaunch airsim_ros_pkgs rviz.launch - ``` -You can view the tfs in rviz. And do a `rostopic list` and `rosservice list` to inspect the services avaiable. - -### Twenty-five drones in a square pattern -- Settings.json - [twenty_five_drones.json](https://github.com/microsoft/AirSim/blob/master/ros/src/airsim_tutorial_pkgs/settings/twenty_five_drones.json) - - ```shell - $ source PATH_TO/AirSim/ros/devel/setup.bash - $ roscd airsim_tutorial_pkgs - $ cp settings/twenty_five_drones.json ~/Documents/AirSim/settings.json - - ## Start your unreal package or binary here - - $ roslaunch airsim_ros_pkgs airsim_node.launch; - $ roslaunch airsim_ros_pkgs rviz.launch - ``` -You can view the tfs in rviz. And do a `rostopic list` and `rosservice list` to inspect the services avaiable. +This page has moved [here](https://github.com/microsoft/AirSim/blob/master/docs/airsim_tutorial_pkgs.md). \ No newline at end of file