Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom

README update suggestion #141

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

README update suggestion #141

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

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 32 additions & 61 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,22 @@
https://user-images.githubusercontent.com/22712178/187902004-480397cc-460f-4d57-8ed7-13f4e9bb3757.mp4

# Introduction

> **Warning** Do not use this software for real drone flights. GISNav is untested and has only been demonstrated
> in a simulation environment.

## Project Overview
GISNav is a ROS 2 package that enables map-based visual navigation for airborne drones **in a simulation environment**.

GISNav provides a *precise* global position by visually comparing frames from the drone's nadir-facing camera to a map
of the drone's *approximate* global position retrieved from an onboard GIS system.

# Mock GPS Example

The below steps demonstrate how GISNav enables GNSS-free flight with PX4 Autopilot's [Mission mode][1] in a SITL
simulation.

You will need to have the [Docker Compose plugin][2] and [NVIDIA Container Toolkit][3] installed.

[1]: https://docs.px4.io/main/en/flight_modes/mission.html
[2]: https://docs.docker.com/compose/install/linux/
[3]: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html
> **Warning** Do not use this software for real drone flights. GISNav is untested and has only been demonstrated
> in a simulation environment.

## Install GISNav CLI
## Prerequisites
This project is built based on ROS 2. Make sure to have the following installed before proceeding:
- [Docker Compose plugin](https://docs.docker.com/compose/install/linux/)
- [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)

The GISNav CLI (`gnc`) is a Docker Compose wrapper that significantly simplifies building and deploying GISNav's Docker Compose services. It is packaged as a Debian distributable.
## Installation Steps
### Manual Installation GISNav CLI
The GISNav CLI (`gnc`) is a Docker Compose wrapper that simplifies building and deploying GISNav's services. It is packaged as a Debian distributable.

Create the Debian distributable and install `gnc` from it using the following commands:

Expand All @@ -33,72 +26,50 @@ cd gisnav
make install
```

## Build and run SITL simulation

Build the Docker images and create and run the containers (downloading and building
everything will take a long time):

> **Note**
> * This script will automatically expose your X server to the created
> Docker containers to make the GUI applications work.
> * We stop autoheal because current healthchecks are quite naive and often
> flag healthy services as unhealthy.
> * Gazebo in the `px4` service will on first run download a number of models
> and will be slow to start up (on first run).
> * `mapserver` service will on first run transfer some files to a shared
> volume and will be slow to start up (on first run).
### VBuild and run SITL simulation
To build the Docker images and create and run the containers (and also verifying the success of the previous step):

```bash
gnc build px4 gisnav --with-dependencies
gnc create px4 gisnav
gnc start px4 gisnav && gnc stop autoheal
```

[4]: http://wiki.ros.org/docker/Tutorials/GUI
> **Note**:
> - Downloading and building everything will take a long time
> - This script will expose your X server to Docker containers for GUI applications.
> - We stop autoheal because current healthchecks are quite naive and often flag healthy services as unhealthy.
> - The `px4` service will download Gazebo models on the first run and may start slowly.
> - The `mapserver` service will transfer files to a shared volume during its first run and may also start slowly.

## Upload flight plan via QGroundControl
## Example Use Case: Mock GPS Example
1. Build and run the SITL simulation as described in the previous step.
2. Upload the sample flight plan (`~/ksql_airport_px4.plan`) via QGroundControl once the Gazebo and QGroundControl windows appear.
3. Start the mission and simulate GPS failure using the MAVLink Shell command:

Once both the Gazebo and QGroundControl windows have appeared (QGroundControl should show the drone location near San
Carlos airport), use QGroundControl to upload the sample `~/ksql_airport_px4.plan` flight plan that is included inside the
Docker container, and then start the mission.

## Simulate GPS failure

Wait until the drone has risen to its final mission altitude. You can then try disabling GPS through your [MAVLink Shell][5]
*(accessible e.g. through QGroundControl > Analyze Tools > MAVLink Console)*:

```
```bash
failure gps off
```

The drone should now continue to complete its mission *GNSS-free* with GISNav substituting for GPS.

You can check if PX4 is receiving the mock GPS position estimates by typing the following in the MAVLink shell:
The drone should continue its mission *GNSS-free*, with GISNav substituting for GPS. Check PX4 receiving the mock GPS position estimates with:

```
```bash
listener sensor_gps
```

> **Note**
> The `gisnav` service will by default send uORB messages to PX4 via the
> micro-ROS agent which bypasses the GPS driver so you will not see the GPS
> status with commands like `gps status`.

[5]: https://docs.px4.io/main/en/debug/mavlink_shell.html#qgroundcontrol
> **Note**: GISNav uses uORB messages to bypass the GPS driver, so commands like `gps status` will not show the GPS status.

Finally, you can stop all simulation services with the below command:
4. Stop all simulation services with:

```bash
gnc stop
```

# Documentation

See the [latest developer documentation][6] for information on how to setup a local environment for GISNav development,
for code examples and API documentation, and integration examples.

[6]: https://hmakelin.github.io/gisnav
## Documentation
See the [latest developer documentation](https://hmakelin.github.io/gisnav) for on how to setup a local environment for GISNav development, for code examples and API documentation, and integration examples.

# License
## Help Information
Feel free to open issues and pull request if you encounter some problems.

## License
This software is released under the MIT license. See the `LICENSE.md` file for more information.