Skip to content
This repository was archived by the owner on Feb 6, 2024. It is now read-only.

Commit 80b2376

Browse files
mrpollomrpollo
committed
Merge pull request dronekit#507 from dronekit/hgw_simulation_update
docs simulation update
2 parents 9d1295b + 59dea1e commit 80b2376

File tree

2 files changed

+99
-72
lines changed

2 files changed

+99
-72
lines changed

Diff for: ‎docs/develop/sitl_setup.rst

+98-71
Original file line numberDiff line numberDiff line change
@@ -4,123 +4,150 @@
44
Setting up a Simulated Vehicle (SITL)
55
=====================================
66

7-
The `SITL (software in the loop) <http://dev.ardupilot.com/wiki/simulation-2/sitl-simulator-software-in-the-loop/>`_
7+
The `SITL (Software In The Loop) <http://dev.ardupilot.com/wiki/simulation-2/sitl-simulator-software-in-the-loop/>`_
88
simulator allows you to create and test DroneKit-Python apps without a real vehicle (and from the comfort of
9-
your own developer desktop!)
9+
your own developer desktop!).
1010

11-
SITL runs natively on Linux and Windows, or within a virtual machine on Mac OSX, Linux or Windows. It can be
11+
SITL can run natively on Linux, Mac and Windows, or within a virtual machine. It can be
1212
installed on the same computer as DroneKit, or on another computer on the same network.
1313

14-
The sections below explain how set up SITL for the different operating systems,
15-
and how you can set up SITL to connect to Mission Planner and DroneKit at the same time.
14+
The sections below explain how install and run SITL, and how to connect to DroneKit-Python and Ground
15+
Stations at the same time.
1616

17-
Setting up SITL on Linux
18-
========================
1917

20-
Build and install SITL on Linux using the instructions in:
21-
`Setting up SITL on Linux <http://dev.ardupilot.com/wiki/setting-up-sitl-on-linux/>`_ (ArduPilot wiki)
18+
DroneKit-SITL
19+
=============
2220

21+
DroneKit-SITL is the simplest, fastest and easiest way to run SITL on Windows, Linux, or MAC OSX.
22+
It is installed from Python's *pip* tool on all platforms, and works by downloading and running pre-built
23+
vehicle binaries that are appropriate for the host operating system.
2324

24-
Setting up SITL on Windows
25-
==========================
25+
This section provides an overview of how to install and use DroneKit-SITL. For more information, see
26+
the `project on Github <https://github.com/dronekit/dronekit-sitl>`_.
2627

27-
Build and install SITL on Windows using the instructions in:
28-
`Setting up SITL on Windows <http://dev.ardupilot.com/wiki/simulation-2/sitl-simulator-software-in-the-loop/sitl-native-on-windows/>`_
29-
(ArduPilot wiki)
28+
.. note::
3029

30+
DroneKit-SITL is still relatively experimental. There are only a few pre-built vehicles and
31+
they have not been as well tested as the native builds.
32+
Please report any issues on `Github here <https://github.com/dronekit/dronekit-sitl/issues>`_.
3133

32-
.. _vagrant-sitl-from-full-image:
34+
Installation
35+
------------
3336

34-
Set up SITL using Vagrant (MacOS)
35-
=================================
37+
The tool is installed (or updated) on all platforms using the command:
3638

37-
This section shows how to bring up a pre-built SITL instance hosted in a `Vagrant <https://www.vagrantup.com/>`_
38-
virtual machine. This approach should be used if you need to run SITL on MacOS. It can also be used for Windows
39-
and Linux (though we recommend the native installations linked above).
39+
.. code-block:: bash
4040
41-
.. warning::
41+
pip install dronekit-sitl -UI
4242
43-
The Vagrant virtual machine is "headless" (has no UI) and so SITL cannot display the MAVProxy map and console.
44-
You can still see and send messages in the SITL Command Prompt.
45-
43+
Running SITL
44+
------------
4645

47-
#. Get the software for hosting the Simulator onto your computer (Windows, OS-X and Linux are supported):
46+
To run the latest version of Copter for which we have binaries (downloading the binaries if needed), you can simply call:
4847

49-
* `Download and install VirtualBox <https://www.virtualbox.org/wiki/Downloads>`_.
50-
* `Download and install Vagrant <https://www.vagrantup.com/downloads.html>`_.
48+
.. code-block:: bash
5149
52-
#. Install SSH (Windows only - SSH is present by default on Linux/Mac OSX)
50+
dronekit-sitl copter
51+
52+
SITL will then start and wait for TCP connections on ``127.0.0.1:5760``.
53+
54+
You can specify a particular vehicle and version, and also parameters like the home location,
55+
the vehicle model type (e.g. "quad"), etc. For example:
5356

54-
* Download and install `Git for Windows <https://git-scm.com/download/win>`_ (or another client that comes with SSH).
55-
After installing you can locate the file using the command ``C:\where ssh`` (normally it is installed to **C:\Program Files (x86)\Git\bin\ssh.exe**
56-
* Add the ssh.exe location to the *Path* (**System Properties | Advanced tab | Environment Variables | Path**)
57+
.. code-block:: bash
5758
58-
#. Create a new directory where you will run *Vagrant*, and open a command prompt/terminal in it:
59+
dronekit-sitl plane-3.3.0 --home=-35.363261,149.165230,584,353
60+
61+
There are a number of other useful arguments:
5962

60-
#. Enter the following commands to fetch a *Vagrantfile* for the pre-built SITL image:
63+
.. code-block:: bash
6164
62-
.. code:: bash
65+
dronekit-sitl -h #List all parameters to dronekit-sitl.
66+
dronekit-sitl copter -h #List additional parameters for the specified vehicle (in this case "copter").
67+
dronekit-sitl --list #List all available vehicles.
68+
dronekit-sitl --reset #Delete all downloaded vehicle binaries.
69+
dronekit-sitl ./path [args...] #Start SITL instance at target file location.
6370
64-
vagrant init 3drobotics/ardupilot-sitl
6571
66-
#. Launch the new image. This takes a long time the *first time* it is run while it downloads the image from the Internet.
72+
.. note::
6773

68-
.. code:: bash
74+
DroneKit-SITL also `exposes a Python API <https://github.com/dronekit/dronekit-sitl#api>`_, which you can use to start simulation from within your scripts. This is particularly useful for test code!
75+
6976

70-
vagrant up
77+
.. _connecting_dronekit_sitl:
7178

72-
#. SSH into the vagrant instance, and start a vehicle:
79+
Connecting to (DroneKit-) SITL
80+
------------------------------
7381

74-
.. code:: bash
82+
SITL waits for TCP connections on ``127.0.0.1:5760``. DroneKit-Python scripts running on the same
83+
computer can connect to the simulation using the connection string as shown:
7584

76-
vagrant ssh
77-
./sitl.sh
78-
79-
When prompted, enter your desired vehicle (e.g. "copter") to build/start SITL.
80-
Once complete, you will see a MAVProxy prompt displaying periodic vehicle-status updates:
85+
.. code-block:: python
8186
82-
.. code:: bash
87+
vehicle = connect('tcp:127.0.0.1:5760', wait_ready=True)
8388
84-
Ready to FLY ublox Received 454 parameters
85-
fence breach
86-
APM: PreArm: RC not calibrated
87-
...
89+
If you need to connect to DroneKit-Python and a ground station at the same time you will need to
90+
`install MAVProxy <http://dronecode.github.io/MAVProxy/html/getting_started/download_and_installation.html>`_
91+
for your system.
8892

89-
.. _disable-arming-checks:
93+
Then in a second terminal you spawn an instance of *MAVProxy* to forward messages from
94+
TCP ``127.0.0.1:5760`` to UDP ports ``127.0.0.1:14550`` and ``127.0.0.1:14551`` (this is what **sim_vehicle.sh** does
95+
if you build SITL from source):
9096

91-
#. Load a default set of parameters and disable the arming check:
97+
.. code-block:: bash
9298
93-
.. code:: bash
94-
95-
STABILIZE>param load ../Tools/autotest/copter_params.parm
96-
STABILIZE>param set ARMING_CHECK 0
99+
mavproxy.py --master tcp:127.0.0.1:5760 --sitl 127.0.0.1:5501 --out 127.0.0.1:14550 --out 127.0.0.1:14551
97100
98-
.. note::
99-
100-
SITL simulates (by default) a vehicle that may not pass the arming check. This change makes the simulated
101-
vehicle more forgiving, which allows the examples to arm and run.
102-
103-
You should never disable the arming check in a script or on a real vehicle.
101+
You can then connect to a ground station using one UDP address, and DroneKit-Python using the other.
102+
For example:
103+
104+
.. code-block:: python
105+
106+
vehicle = connect('127.0.0.1:14550', wait_ready=True)
107+
108+
109+
110+
Building SITL from source
111+
=========================
112+
113+
You can natively build SITL from source on Linux, Windows and Mac OS X,
114+
or from within a Vagrant Linux virtual environment.
115+
116+
Building from source is useful if you want to need to test the latest changes (or any use
117+
a version for which DroneKit-SITL does not have pre-built binaries).
118+
It can also be useful if you have problems getting DroneKit-SITL to work.
119+
120+
The following topics from the ArduPilot wiki explain how:
121+
122+
* `Setting up SITL on Linux <http://dev.ardupilot.com/wiki/setting-up-sitl-on-linux/>`_
123+
* `Setting up SITL on Windows <http://dev.ardupilot.com/wiki/simulation-2/sitl-simulator-software-in-the-loop/sitl-native-on-windows/>`_
124+
* `Setting up SITL using Vagrant <http://dev.ardupilot.com/wiki/setting-up-sitl-using-vagrant/>`_
104125

105126

106127
.. _viewing_uav_on_map:
107128

108129
Connecting an additional Ground Station
109130
=======================================
110131

111-
This section explains how you can connect multiple ground stations to a running SITL instance in addition to your DroneKit MAVProxy link.
132+
You can connect a ground station to an unused port to which messages
133+
are being forwarded. You can forward messages to additional ports
134+
when you start *MAVProxy* using the using ``-out``
135+
parameter (as shown :ref:`above <connecting_dronekit_sitl>`).
112136

113-
To do this you first need to get SITL to output to an additional UDP port of your computer:
137+
Alternatively, once *MAVProxy* is started you can add new output ports in the *MAVProxy* console using: ``output add``:
138+
139+
.. code:: bash
140+
141+
output add 127.0.0.1:14552
142+
143+
.. note::
144+
145+
Instead of the loopback address you can also specify the network IP address of your computer
146+
(On Windows you can get this by running *ipconfig* in the *Windows Command Prompt*).
114147

115-
* Find the network IP address of your computer (On Windows you can get this by running *ipconfig* in the *Windows Command Prompt*).
116-
* In the *SITL Command Prompt*, add the IP address of the GCS computer (e.g. 192.168.2.10) and an unused port (e.g. 145502) as an output:
117-
118-
.. code:: bash
119-
120-
output add 192.168.2.10:14552
121148

122149
Then connect Mission Planner to this UDP port:
123-
150+
124151
* `Download and install Mission Planner <http://ardupilot.com/downloads/?did=82>`_
125152
* Ensure the selection list at the top right of the Mission Planner screen says *UDP* and then select the **Connect** button next to it.
126153
When prompted, enter the port number (in this case 14552).

Diff for: ‎docs/guide/quick_start.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ On Linux you will first need to install **pip** and **python-dev**:
2828
sudo apt-get install python-pip python-dev
2929
3030
31-
See :doc:`installation` and `dronekit-sitl <https://github.com/dronekit/dronekit-sitl#dronekit-sitl>`_
31+
See :doc:`../develop/installation` and `dronekit-sitl <https://github.com/dronekit/dronekit-sitl#dronekit-sitl>`_
3232
for more detailed installation instructions.
3333

3434

0 commit comments

Comments
 (0)