[WIP] Integrate BlueRov examples

en/SUMMARY.md

@@ -14,7 +14,8 @@
     * [Examples](mavgen_c/examples.md)
       * [UART Interface (C)](mavgen_c/example_c_uart.md)
       * [UDP Example (C)](mavgen_c/example_c_udp.md)
-  * [Python (mavgen)](mavgen_python/README.md)
+  * [Pymavlink (mavgen-Python)](mavgen_python/README.md)
+    * [Pymavlink BlueRobotics TEST](mavgen_python/pymavlink.md)
 * [Guide](guide/README.md)
   * [MAVLink Versions](guide/mavlink_version.md)
   * [MAVLink 2](guide/mavlink_2.md)

en/mavgen_python/README.md

@@ -3,7 +3,7 @@
 Pymavlink is a *low level* and *general purpose* MAVLink message processing library, written in Python.
 It has been used to implement MAVLink communications in many types of MAVLink systems, including a GCS (MAVProxy), Developer APIs (DroneKit) and numerous companion computer MAVLink applications.
 
-The library can be used with Python 2.7+ (recommended) or Python 3.5+ and supports both MAVLink 1 and MAVLink 2 versions of the protocol.
+The library can be used with Python 3.5+ and supports both MAVLink 1 and MAVLink 2 versions of the protocol.
 
 This topic explains how to get and use the *Pymavlink* MAVLink Python libraries (generated using [mavgen](../getting_started/generate_libraries.md#mavgen)).
 
@@ -16,7 +16,10 @@ This topic explains how to get and use the *Pymavlink* MAVLink Python libraries
   These implement a number of [MAVLink microservices](../about/overview.md).
 
 ## Getting the Python MAVLink Libraries
-The following are instructions for how to obtain the MAVLink libraries for the standard and custom dialects. If the standard dialect is to be used, the instructions are much simpler. For custom dialects the library needs to be generated first.
+
+The following are instructions for how to obtain the MAVLink libraries for the standard and custom dialects.
+If the standard dialect is to be used, the instructions are much simpler.
+For custom dialects the library needs to be generated first.
 
 ### Get the Standard MAVLink Dialect
 
@@ -29,6 +32,7 @@ pip install pymavlink
 
 
 ### Generate a Custom MAVLink Dialect
+
 If you need libraries for a *custom dialect* then you will need to [install the code generator mavgen](../getting_started/installation.md) and [generate](../getting_started/generate_libraries.md) the libraries yourself.
 You will also need to include them in *pymavlink* and install them locally on your system.
 
@@ -38,30 +42,35 @@ You will also need to include them in *pymavlink* and install them locally on yo
    - MAVLink 1: **pymavlink/dialects/v10**
 1. Open a command prompt and navigate to the **pymavlink** directory.
 1. If needed, uninstall previous versions:
+
    ```
    pip uninstall pymavlink
    ```
 1. Install dependencies if you have not previously installed pymavlink using *pip*:
+
    ```
-   pip install lxml future
+   python3 -m pip install -r pymavlink/requirements.txt
    ```
 1. Run the python setup program:
+
    ```bash
    python setup.py install --user
    ```
 
 The generated MAVLink libraries can then be used in the same way as those installed using *pip*.
 
-
 ## Using the Python MAVLink Libraries
 
 ### Overview
 
 The *pymavlink* package includes the dialect-specific generated modules, which provide low-level functionality to encode and decode messages, and apply and check signatures.
 
-Generally speaking, most developers will use the **mavutil** module to set up and manage the communication channel, because it makes getting started very easy. This module provides simple mechanisms for setting up links, sending and receiving messages, and querying some basic autopilot properties such as the currently active flight mode for example. It provides access to the dialect module used for encoding, decoding and signing messages via an attribute (`mav`).
+Generally speaking, most developers will use the **mavutil** module to set up and manage the communication channel, because it makes getting started very easy.
+This module provides simple mechanisms for setting up links, sending and receiving messages, and querying some basic autopilot properties such as the currently active flight mode for example.
+It provides access to the dialect module used for encoding, decoding and signing messages via an attribute (`mav`).
 
 There are several main caveats to be aware of when using **mavutil**:
+
 - The link does not properly handle multiple systems running on the same port. 
   If you need a multi-vehicle network see [source-system-filtering](https://github.com/peterbarker/dronekit-python/tree/source-system-filtering/examples/multivehicle).
 - The module is optimised for ArduPilot and some functions may not work properly on other autopilots.
@@ -72,6 +81,7 @@ There are several main caveats to be aware of when using **mavutil**:
   In particular the connection code and methods to filter incoming messages are useful for any autopilot.
 
 The set of modules in the *pymavlink* package are listed below:
+
 - **\dialects\v20\\*** and **\dialects\v10\\***: Dialect modules corresponding to each source XML [message definition](../messages/README.md) for MAVLink v2 and v1, respectively. 
   Each dialect module contains:
   - constants for all enums and enum values defined in the XML file.
@@ -90,22 +100,24 @@ The set of modules in the *pymavlink* package are listed below:
 - **[mavwp](https://github.com/ArduPilot/pymavlink/blob/master/mavwp.py)**: Load/save waypoints, geofence, rally points.
 - **[mavparm](https://github.com/ArduPilot/pymavlink/blob/master/mavparm.py)**: Load/save sets of MAVLink parameters.
 - **[mavextra](https://github.com/ArduPilot/pymavlink/blob/master/mavextra.py)**: Useful functions for converting values and messages (e.g. metres/second to Km/h, eulers in radians from quaternion etc.).
-- **[mavexpression]()** (internal): MAVLink expression evaluation functions.
+- **[mavexpression](https://github.com/ArduPilot/pymavlink/blob/master/mavexpression.py)** (internal): MAVLink expression evaluation functions.
 
 
 ### Choosing the Dialect/MAVLink Version {#dialect_file}
 
-Choosing the Dialect/MAVLink version depends on whether you are using **mavutil** for link management or working directly with dialect files. 
+Choosing the Dialect/MAVLink version depends on whether you are using **mavutil** for link management or working directly with dialect files.
 
 By default **mavutil** sets up the link to use the MAVLink 1 `ardupilotmega` dialect for sending/receiving. 
 You can change this by setting environment variables:
+
 - `MAVLINK_DIALECT`: Set to string name for the dialect file (without XML extension).
 - `MAVLINK20`: Set to 1 (if unset then default to MAVLink 1)
 - `MDEF`: Location of message definition libraries
 
 > **Tip** You can also change the dialect by passing its name to `mavutil.mavlink_connection()` when [setting up a connection](#setting_up_connection).
 
 If you are not using *mavutil* then you can import the dialect file that you want to use directly:
+
 ```python
 # Import ardupilotmega module for MAVLink 1
 from pymavlink.dialects.v10 import ardupilotmega as mavlink1
@@ -116,7 +128,8 @@ from pymavlink.dialects.v20 import common as mavlink2
 
 ### Setting up a Connection {#setting_up_connection}
 
-The **mavutil** module provides the `mavlink_connection()` method for setting up communication links to MAVLink systems over serial ports, tcp, or udp channels. It can also connect to a file object, which is useful when working with telemetry logs.
+The **mavutil** module provides the `mavlink_connection()` method for setting up communication links to MAVLink systems over serial ports, tcp, or udp channels.
+It can also connect to a file object, which is useful when working with telemetry logs.
 
 > **Warning** The method returns an object that represents a single system, but will collect messages from multiple systems on the link.
   This is OK for two-system networks, but if you need to connect over a multi-vehicle IP network see [source-system-filtering](https://github.com/peterbarker/dronekit-python/tree/source-system-filtering/examples/multivehicle).
@@ -153,11 +166,14 @@ Other `mavlink_connection()` parameters you may wish to change include: `source_
 #### Connection Strings {#connection_string}
 
 The `mavutil.mavlink_connection()` connection string has the format:
+
 ```
 [protocol:]address[:port]
 ```
+
 where:
-- *protocol* (optional): 
+
+- `protocol` (optional): 
   The IP protocol. 
   If not specified pymavlink will attempt to determine if the address is a serial port (e.g. USB) or a file, and if not will default to a UDP address.
   - `tcp`: Initiate a TCP connection on the specified `address` and `port`.
@@ -166,25 +182,24 @@ where:
   - `udpout`: Initiate a TCP connection on the specified `address` and `port`.
   - `udp`: By default, same as `udpin`. Set `mavlink_connection` parameter `input=False` to make same as `udpout`.
   - `udpcast`: Broadcast UDP address and port. This is the same as `udp` with `mavlink_connection()` parameters `input=False` and `broadcast=True`.
-- *address*: IP address, serial port name, or file name
-- *port*: IP port (only if address is an IP address)
+- `address`: IP address, serial port name, or file name
+- `port`: IP port (only if address is an IP address)
 
 Some of the strings you can use for different types of connections are listed below.
 
 Connection type | Connection string
 --- | ---
-Linux computer connected to the vehicle via USB | /dev/ttyUSB0
-Linux computer connected to the vehicle via Serial port (RaspberryPi example) | /dev/ttyAMA0 (also set baud=57600)
-MAVLink API listening for SITL connection via UDP | udpin:localhost:14540 (or udp:localhost:14540, 127.0.0.1:14540,etc.) 
-MAVLink API initiating a connection to SITL via UDP | udpout:localhost:14540 (or udpout:127.0.0.1:14540)
-GCS connected to the vehicle via UDP | 127.0.0.1:14550 or udp:localhost:14550
-SITL connected to the vehicle via TCP | tcp:127.0.0.1:5760 (ArduPilot only, PX4 does not support TCP)
-OSX computer connected to the vehicle via USB | dev/cu.usbmodem1
-Windows computer connected to the vehicle via USB (in this case on COM14) | com14
-Windows computer connected to the vehicle using a 3DR Telemetry Radio on COM14 | com14 (also set baud=57600)
-
-> **Note** While MAVLink does not define the UDP ports used for different purposes, there is a *defacto* standard that MAVLink APIs should listen for SITL connections on UDP port 14540 while a GCS should listen for connections on UDP 14550.
+Linux computer connected to the vehicle via USB | `/dev/ttyUSB0`
+Linux computer connected to the vehicle via serial port (RaspberryPi example) | `/dev/ttyAMA0` (also set `baud=57600`)
+MAVLink API listening for SITL connection via UDP | `udpin:localhost:14540` (or `udp:localhost:14540`, 127.0.0.1:14540,etc.) 
+MAVLink API initiating a connection to SITL via UDP | `udpout:localhost:14540` (or `udpout:127.0.0.1:14540`)
+GCS connected to the vehicle via UDP | `127.0.0.1:14550` or `udp:localhost:14550`
+SITL connected to the vehicle via TCP | `tcp:127.0.0.1:5760` (ArduPilot only, PX4 does not support TCP)
+OSX computer connected to the vehicle via USB | `dev/cu.usbmodem1`
+Windows computer connected to the vehicle via USB (in this case on COM14) | `com14`
+Windows computer connected to the vehicle using a 3DR Telemetry Radio on `COM14` | `com14` (also set `baud=57600`)
 
+> **Note** While MAVLink does not define the UDP ports used for different purposes, there is a *defacto* standard that MAVLink APIs should listen for SITL connections on UDP port `14540` while a GCS should listen for connections on UDP `14550`.
 
 
 ### Sending Messages {#sending}
@@ -233,6 +248,7 @@ except:
 ```
 
 Alternatively you can use the **mavutil** `recv_match()` method to wait for and intercept messages as they arrive:
+
 ```python
 def recv_match(self, condition=None, type=None, blocking=False, timeout=None):
     '''Receive the next MAVLink message that matches the given type and condition
@@ -244,16 +260,19 @@ def recv_match(self, condition=None, type=None, blocking=False, timeout=None):
 ```
 
 For example using `the_connection` set up as before, you can wait for *any* message as shown:
+
 ```python
 msg = the_connection.recv_match(blocking=True)
 ```
 If you instead want to just get a particular message with certain attribute values you might instead do:
+
 ```python
 # Wait for a 'SYS_STATUS' message with the specified values.
 msg = the_connection.recv_match(type='SYS_STATUS', condition='SYS_STATUS.mode==2 and SYS_STATUS.nav_mode==4', blocking=True)
 ```
 
 You should also check that the message is valid before attempting to use it:
+
 ```python
 msg = m.recv_match(type='SYS_STATUS',blocking=True)
 if not msg:
@@ -272,7 +291,6 @@ The returned object is the subclass of `MAVLink_message` for the specific messag
 You can access the message fields as class attributes as shown for the mode in the above code fragment.
 If needed, you can query `MAVLink_message` for information about the signature, CRC and other header information.
 
-
 #### Requesting Specific Messages {#specific_messages}
 
 A remote system will typically stream a *default* set of messages to a connected GCS, camera or other system.

en/mavgen_python/_examples/advanced_servo_gripper.py

@@ -0,0 +1,155 @@
+"""
+Advanced example of how to control servo outputs with pymavlink.
+Includes extended example for controlling a Blue Robotics' gripper.
+
+Requires Python 3.
+
+"""
+
+# Import mavutil
+from pymavlink import mavutil
+
+class RawServoOutput:
+    """ A class for commanding a mavlink-controlled servo output port. """
+    # https://mavlink.io/en/messages/common.html#MAV_CMD_DO_SET_SERVO
+    CMD_SET = mavutil.mavlink.MAV_CMD_DO_SET_SERVO
+
+    def __init__(self, master, instance, pwm_limits=(1100, 1500, 1900),
+                 set_default=True):
+        """ Initialise a RawServoOutput instance.
+
+        'master' is a mavlink connection
+        'instance' is the servo output (e.g. Pixhawk MAIN 1-8, AUX 9-16)
+        'pwm_limits' is a tuple of min, default, and max pwm pulse-widths
+            in microseconds (default (1100, 1500, 1900)).
+        'set_default' is a boolean specifying whether to command the output
+            to the specified default pulse-width (default True).
+
+        """
+        self.master     = master
+        self.instance   = instance
+        self.min_us, self._current, self.max_us = pwm_limits
+        self._diff      = self.max_us - self.min_us
+
+        if set_default:
+            self.set_direct(self._current)
+
+    def set_direct(self, us):
+        """ Directly set the PWM pulse width.
+
+        'us' is the PWM pulse width in microseconds.
+            Must be between self.min_us and self.max_us.
+
+        """
+        assert self.min_us <= us <= self.max_us, "Invalid input value."
+
+        # self.master.set_servo(self.instance, us) or:
+        self.master.mav.command_long_send(
+            self.master.target_system, self.master.target_component,
+            self.CMD_SET,
+            0, # first transmission of this command
+            self.instance, us,
+            0,0,0,0,0 # unused parameters
+        )
+        self._current = us
+
+    def set_ratio(self, proportion):
+        """ Set the PWM pulse-width ratio (auto-scale between min and max).
+
+        'proportion' is a 0-1 value, where 0 corresponds to self.min_us, and
+            1 corresponds to self.max_us.
+
+        """
+        self.set_direct(proportion * self._diff + self.min_us)
+
+    def inc(self, us=50):
+        """ Increment the PWM pulse width by 'us' microseconds. """
+        self.set_direct(max(self.max_us, self._current+us))
+
+    def dec(self, us=50):
+        """ Decrement the PWM pulse width by 'us' microseconds. """
+        self.set_direct(min(self.min_us, self._current-us))
+
+    def set_min(self):
+        """ Set the PWM to self.min_us. """
+        self.set_ratio(0)
+
+    def set_max(self):
+        """ Set the PWM to self.max_us. """
+        self.set_ratio(1)
+
+    def center(self):
+        """ Set the PWM to half-way between self.min_us and self.max_us. """
+        self.set_ratio(0.5)
+
+
+class AuxServoOutput(RawServoOutput):
+    """ A class representing a mavlink-controlled auxiliary servo output. """
+    def __init__(self, master, servo_n, main_outputs=8, **kwargs):
+        """ Initiliase a servo instance.
+
+        'master' is a mavlink connection.
+        'servo_n' is one of the auxiliary servo outputs, like the servo_n
+            outputs with QGroundControl joystick control.
+            Most likely a value between 1-3, but possibly up to 6 or 8
+            depending on setup.
+        'main_outputs' is the number of MAIN outputs are present on the
+            autopilot device (default 8).
+        **kwargs are passed to RawServoOutput.
+
+        """
+        super().__init__(master, servo_n+main_outputs, **kwargs)
+        self._main_outputs = main_outputs
+
+    @property
+    def servo_n(self):
+        """ Return the AUX servo number of this output. """
+        return self.instance - self._main_outputs
+
+
+class Gripper(AuxServoOutput):
+    """ A class representing a Blue Robotics' gripper. """
+    def __init__(self, master, servo_n, pwm_limits=(1100, 1100, 1500),
+                 **kwargs):
+        """ Initialise a Gripper instance.
+
+        'master' is a mavlink connection.
+        'servo_n' is one of the auxiliary servo outputs, like the servo_n
+            outputs with QGroundControl joystick control.
+            Most likely a value between 1-3, but possibly up to 6 or 8
+            depending on setup.
+        'pwm_limits' is a tuple of min, default, and max pwm pulse-widths
+            in microseconds (default (1100, 1100, 1900)).
+        **kwargs are passed to AuxServoOutput.
+
+        """
+        super().__init__(master, servo_n, pwm_limits=pwm_limits, **kwargs)
+
+    def open(self):
+        """ Command the gripper to open. """
+        self.set_max()
+
+    def close(self):
+        """ Command the gripper to close. """
+        self.set_min()
+
+
+# if running this file as a script:
+if __name__ == '__main__':
+    from time import sleep
+
+    # Connect to the autopilot (pixhawk) from the surface computer,
+    #  via the companion.
+    autopilot = mavutil.mavlink_connection('udpin:0.0.0.0:14550')
+    # Wait for a heartbeat from the autopilot before sending commands
+    autopilot.wait_heartbeat()
+
+    # create a gripper instance on servo_1 (AUX output 1)
+    gripper = Gripper(autopilot, 1)
+
+    # open and close the gripper a few times
+    for _ in range(3):
+        gripper.open()
+        sleep(2)
+        gripper.close()
+        sleep(1)