add pypilot

Author: sailoog

index.rst

@@ -56,7 +56,7 @@ Welcome to OpenPlotter's documentation!
 
 .. toctree::
    :maxdepth: 1
-   :caption: Serial - 3.2.0-stable
+   :caption: Serial - 3.3.0-stable
    :name: sec-serial
 
    serial/serial_app
@@ -85,11 +85,14 @@ Welcome to OpenPlotter's documentation!
 
 .. toctree::
    :maxdepth: 1
-   :caption: Pypilot- 3.2.12-stable
+   :caption: Pypilot- 3.2.13-stable
    :name: sec-pypilot
 
    pypilot/pypilot_app
+   pypilot/imu
+   pypilot/autopilot
    pypilot/calibration
+   pypilot/more
 
 .. toctree::
    :maxdepth: 1

pypilot/autopilot.rst

@@ -0,0 +1,124 @@
+.. |OPserialUart| image:: img/uart.png
+.. |OPserialConnections| image:: img/connections.png
+.. |OPserialUSB| image:: img/usb.png
+.. |OPserialApply| image:: img/apply.png
+.. |PYservice| image:: img/process.png
+.. |PYautopilot| image:: img/autopilot.png
+.. |PYcontrol| image:: img/control.png
+.. |PYopen| image:: img/open.png
+.. |PYplugin| image:: img/plugin.png
+
+Autopilot mode
+##############
+
+Enable this mode in the |PYservice| *Services* tab **only** if you are using a Pypilot motor controller:
+
+.. image:: img/pypilot5.png
+
+You also need one of the IMUs recommended in the previous chapter. Do not forget to :ref:`calibrate<calibration>`.
+
+The motor controller can be purchased from the official `Pypilot store <https://pypilot.org/opencart/>`_.
+
+As a motor you can use the one from your old autopilot if it still works or an `industrial equivalent <https://pcnautic.nl/nl/autopilot/pcnautic-bare-tillerdrive-detail>`_ like these replacements for the `Raymarine Q047 <https://pcnautic.nl/nl/autopilot/raymarine-q047-replacement-detail>`_, the `EV-100/SPX-5 <https://pcnautic.nl/nl/autopilot/ev-100-spx-5-tiller-drive-replacement-set-detail>`_ or the `ST4000+ <https://pcnautic.nl/nl/autopilot/st4000-tiller-drive-replacement-set-detail>`_. But you can also use `other types of motors <https://pypilot.org/wiki/doku.php?id=rudder_drive_motor>`_ that are not normally used in marine environments.
+
+Finally you might also need the Pypilot HAT to control the autopilot although this element is optional because you have other ways to control it as we will see later. The Pypilot HAT can be purchased from the official `Pypilot store <https://pypilot.org/opencart/>`_.
+
+Connecting the motor controller
+*******************************
+
+On one side you have to connect the controller to the motor and on the other side to one of the UART ports of the Raspberry Pi following this scheme:
+
++--------------------------+--------------+
+| Pypilot motor controller | Raspberry Pi |
++===========+==============+==============+
+| Vcc                      | 3V3          |
++--------------------------+--------------+
+| RxD                      | UART TX      |
++--------------------------+--------------+
+| TxD                      | UART RX      |
++--------------------------+--------------+
+| GND                      | GND          |
++--------------------------+--------------+
+
+You can use any of the available UART interfaces on your Raspberry Pi model. See the :ref:`UART<uart>` chapter to find out which one to choose.
+
+In the following example we are going to use the UART0 interface which is the only one available for both the Raspberry Pi 3 and 4 models. Go to the |OPserialUSB| *OpenPlotter Serial* app and click the |OPserialUart| ``UART0`` button, acknowledge the warning and reboot. After the reboot, launch the |OPserialUSB| *OpenPlotter Serial* app again. On the |OPserialUSB| ``Devices`` tab, you should now see a new entry. Select the line with *ttyAMAx*, give it an *alias* (for example *pypilot*) and select *NMEA 0183* from the *data* dropdown, then press |OPserialApply| ``Apply``:
+
+.. image:: img/pypilot6.png
+
+Finally we need to connect the ttyOP_pypilot device to Pypilot. Switch to the |OPserialConnections| ``Connections`` tab, select the *ttyOP_pypilot* device and click |PYautopilot| ``Add to Pypilot``:
+
+.. image:: img/pypilot7.png
+
+In the next window click ``AUTO`` and that is it. The motor controller will be ready to receive orders from Pypilot.
+
+
+Feeding data to autopilot
+*************************
+
+Pypilot receives data from the IMU and forwards it to the Signal K server automatically when we steer in *compass mode* using the magnetic heading as reference.
+
+We can also steer in *GPS mode*, using the course over ground as reference, or in *wind mode* and *true wind mode*, keeping the apparent wind angle or the true wind angle respectively. In these cases, Pypilot will get the necessary data from the Signal K server automatically when these devices are defined there. If we want to decrease the latency of this data we can also add these devices directly to Pypilot using the |OPserialUSB| *OpenPlotter Serial* app in the same way that we have added the motor controller. Pypilot will take care of sending the data from these devices also to the Signal K server so that other programs can use them.
+
+Autopilot control
+*****************
+
+.. image:: img/pypilot8.png
+
+Once we have connected the hardware and we are feeding Pypilot with the necessary data, we can start to control our autopilot using any of the available interfaces. All interfaces can be used in parallel and have all the options you would normally find on any autopilot.
+
+Only one of them is physical and the rest are virtual. The virtual control interfaces can be used from the same device running OpenPlotter and two of them can also be used remotely from other devices, such as a mobile phone connected to the same network as OpenPlotter. The physical control interface, the Pypilot HAT, can also be used remotely via an infrared remote control.
+
+All control interfaces share the same options and parameters that we will briefly explain later.
+
+|PYcontrol| **Control**
+
+.. image:: img/interface_control.png
+
+You can access this virtual interface only from the system running OpenPlotter by clicking the |PYcontrol| ``Control`` icon in the |PYautopilot| *OpenPlotter Pypilot* app.
+
+|PYopen| **Web Control**
+
+.. image:: img/interface_browser.png
+
+You can access this virtual interface from the system running OpenPlotter by clicking the |PYopen| ``Web Control`` icon in the |PYautopilot| *OpenPlotter Pypilot* app or by typing the address *https://localhost:8000* in the browser. Before you can use this interface you need to activate it in the |PYservice| *Services* tab, checking the ``Enable Web Control`` option.
+
+You can also use this interface remotely from any device connected to the same network as your OpenPlotter system by typing the address *https://openplotter.local:8000* in the browser.
+
+|PYplugin| **OpenCPN plugin**
+
+.. image:: img/interface_plugin.png
+
+You can access this virtual interface from the system running OpenPlotter by installing and enabling the *pypilot* plugin in OpenCPN. Before you can use this interface, you must connect pypilot by clicking ``Config`` and supplying the *host*. The *host* is *localhost* when your pypilot instance runs on the same system as OpenCPN or *openplotter.local* when your pypilot instance runs on another system on the same network.
+
+**Pypilot HAT**
+
+This is the physical interface of Pypilot. It basically consists of a small LCD digital screen, a small keyboard and an infrared sensor for a remote control. Before you can use this interface you need to activate it in the |PYservice| *Services* tab, checking the ``Enable HAT Control`` option.
+
+Pypilot should automatically detect the HAT. You can modify some parameters by clicking the ``Configure`` button or by typing the address *https://localhost:33333* in the browser. Note that the web interface at port 33333 has a startup delay of 30 seconds.
+
+
+Parameters
+**********
+
+These are some of the parameters that you will find in all control interfaces:
+
+:AP: 
+
+:Heading: [Heading - Command]
+
+:Mode: [Compass - GPS - Wind - True Wind]
+
+:<< < > >>: 
+
+:Tack: [starboard - board]
+
+:Gain: [P - I - D - DD - PR - FF]
+
+:Rudder:
+
+:Settings:
+
+:Client:
+
+:Scope: 

pypilot/calibration.rst

@@ -1,7 +1,71 @@
 .. _calibration:
 
+.. |PYcali| image:: img/calibration.png
+.. |PYautopilot| image:: img/autopilot.png
 
-Compass calibration
-###################
+|PYcali| Compass calibration
+############################
 
-**Coming soon**
+Follow these steps in order:
+
+1. Accelerometer bias
+*********************
+
+IMUs require accelerometer bias calibration. Without it, there will be significant pitch and roll errors. Most of them are factory calibrated, which means you could skip this step, but it is recommended to calibrate the accelerometer bias, even if it is factory calibrated, as it will slightly improve the factory calibration.
+
+To calibrate the accelerometer bias, you must be on a *mostly* stable platform. It may be impossible to do at anchor if the boat is moving too much, so either in flat water, or land for this step.
+
+Go to |PYautopilot| *OpenPlotter Pypilot* app and click on |PYcali| ``Calibration``. In Calibration window click on ``accel`` tab. Make sure *calibration locked* is not enabled.
+
+Carefully place the sensor on each of the 6 sides of a box (+- 10 degrees will do) the actual orientation is not critical, so long as enough measurements can be taken to fit a sphere. Leave the sensors in each position for a few seconds.
+
+Once a calibration is applied the accelerometer *Calibration Age* should reset and fit points become yellow. If it does not, repeat the process putting the sensors in different orientations until a calibration fix is found.
+
+.. image:: img/calibration0.png
+.. image:: img/calibration1.png
+
+If you use the cheapest sensors, sometimes they have bad accelerometers. Either one axis will always read zero, or they will saturate because the bias is greater than 1g. This is easy to determine from the accelerometer calibration plot in calibration window. 
+
+
+2. Alignment
+************
+
+Once the accelerometer is calibrated, the sensor should be fixed securely to the boat. Alignment and compass calibration are required for correct operation. If sensors are moved or remounted, this must be performed again (but not accelerometer calibration).
+
+To perform alignment, ensure the boat is level (not heeling or pitching) and in relatively calm water (small waves motion of a few degrees is ok). Go to ``alignment`` tab and click  ``Boat is level`` button.
+
+.. image:: img/calibration2.png
+
+Correct alignment must be performed before the compass calibration can begin. 
+
+.. image:: img/calibration3.png
+
+
+3. Compass
+**********
+
+Be sure to locate the sensors away from:
+
+- magnets - speakers and especially moving magnets like floating compasses.
+- current carrying wires - very simple rule is 2 cm (1 inch) for every amp.
+- iron and steel - less critical. If you are in a steel boat, just do not fix the sensors to a steel wall and try to locate them several inches at least offset from it.
+
+The compass calibration is mostly automatic. If the accelerometer and alignment are calibrated, you just need to sail turning more than 180 degrees to calibrate the compass.
+
+Go to ``compass`` tab and make sure *calibration locked* is not enabled or updates will not occur.
+
+There are both 2D and 3D compass calibration fixes. A 2D fix will occur from turning without pitching or heeling. When heeling there may be some error without a 3D fix. To obtain a 3D fix, you should make a circle with sufficient heeling, such as tacking against the wind, or rolling in waves.
+
+Subsequent 2D fixes will use the previous undetermined value for 3D fix, combining the new 2D fix with the past information from a 3D fix. Performing accelerometer calibration will give a rough 3D fix in most cases making a subsequent 2D fix sufficient for most use.
+
+Compass calibration is continuous and always updates unless locked. You may want to lock it to prevent future calibration updates when you know there is compass interference, but unlocking it is recommended.
+
+.. image:: img/calibration4.png
+
+Once a new calibration is applied, the accelerometer *Calibration Age* should reset and fit points become yellow.
+
+.. image:: img/calibration5.png
+
+If the sensors are remounted, they must be re-aligned and the compass recalibrated.
+
+If metal objects are moved around the sensors, the compass must recalibrate.