High Level About this Pull Request

As previously discussed with @dagar, this pull request seeks to further couple the relationship between the PX4 flight controller and Vertiq modules. At its core, this PR introduces the IQUART serial protocol into PX4, and in doing so provides the flight controller with the ability to control and configure connected Vertiq modules

IQUART and its Clients

The IQUART serial protocol is built around its ability to communicate with a series of Clients and Entries available on Vertiq modules. All IQUART messages specify a target module ID, type ID, and type sub-ID. Type IDs refer to unique identification values given to each different IQUART client. Sub-IDs refer to specific entries within the client. For example, the Serial Interface Client (type ID 16) provides one entry with sub-ID 0.

A key portion of this PR is the inclusion of Vertiq’s C++ library as a git submodule. The library provides a C++ representation of all possible Veritq clients as well as functions for packaging proper IQUART messages.

What We’ve Added to PX4

Basic User Interface

The following examples are performed using a Pixhawk 6c using the Generic Quadcopter airframe. These serve to help in understanding the structure of the backend Vertiq support.

Boardconfig Options

• Vertiq IO
  Provides access to basic Vertiq module configuration through PX4 parameters. This configuration alone is not enough for flight through the IQUART protocol, but could be helpful in configuration where other protocols, such as DroneCAN, are being used to send throttle commands.
• Include IFCI Configuration Parameters
  Provides access to parameters specific to the IQUART Flight Controller Interface. Enabling this configuration allows users to control a vehicle and receive telemetry from Vertiq modules through the serial port configured to vertiq_io.
• Include Pulsing Module Configuration Parameters
  Provides access to specialized parameters available only for “pulsing modules.” These are modules equipped with specialized Vertiq firmware and our Vertiq UP12 propeller.

Configuration with QGroundControl

At the moment, the easiest way for users to interact with and configure our modules is through Vertiq’s IQ Control Center software. As you can imagine, having to unplug serial connections from PX4 and reconnect them to the Control Center is a laborious process. While users could add an extra serial connection to use serial passthrough, this is not always possible. Therefore, by providing module configuration functionality directly to the flight controller, we make our users’ lives much easier.

After selecting a serial port

When the matching baud rate is set, we see the module with the matching Module ID to TARGET_MODULE_ID’s parameters appear. With this configuration, those parameters are MAX_VELOCITY, MAX_VOLTS, CONTROL_MODE, THROTTLE_CVI, VERTIQ_FC_DIR, and VERTIQ_MOTOR_DIR.

The parameters that change based on the value of TARGET_MODULE_ID are those managed by the Vertiq Configuration Handler class.

Target Module ID 0

Target Module ID 1

I did not change any values besides the TARGET_MODULE_ID, and you can see that the other Vertiq parameters were updated with values gotten from the module with ID 1.

Code Structure

Class Descriptions

Vertiq IO

• Responsible for spawning our task, and contains our run()
• Contains our updateOutputs function for motor control
• Contains 3 Vertiq Clients used as part of motor control: a Propeller Motor Control Client, an Arming Handler Client, and an IFCI - Client all set to broadcast to all connected modules
• Creates and updates all other objects used in the module

Vertiq Serial Interface

• Responsible for configuring the selected hardware serial port
• Responsible for reading data from the serial peripheral and passes it to the active Vertiq clients
• Responsible for taking data written by the active Vertiq clients, and writing out data to the serial peripheral

Vertiq Client Manager

• Can be given new Vertiq clients of any type to manage by any external object
• Manages a list of clients up to a predefined maximum amount
• Handles client communication by periodically telling the serial interface to transmit queued messages and to have each client process received data

Vertiq Configuration Handler

• Responsible for maintaining any Vertiq client objects which are created and destroyed as TARGET_MODULE_ID changes
• Responsible for managing a list of EntryWrapper objects
  EntryWrappers are used to link together a PX4 parameter and a Vertiq Client’s Entry, and are covered in more detail later

Vertiq Telemetry Manager

• Responsible for maintaining an IQUART Flight Controller Interface client which gets created and destroyed as the Module ID for telemetry changes
• Responsible for generating the correct Module ID for the next module whose telemetry we want
• Responsible for publishing to the esc_status uORB topic the data received from modules

About EntryWrapper Objects

As mentioned above, an EntryWrapper is an object meant to connect a PX4 parameter with a Vertiq Client Entry. The goal is to ensure that when an EntryWrapper’s PX4 parameter changes, that the same change is reflected on the connected motor with the module ID TARGET_MODULE_ID.
The process for updating EntryWrappers is described by the following diagrams. The top describes what happens at a higher level when any Vertiq parameter is changed, and the bottom describes the decisions made by the EntryWrapper itself during its update.

High Level

Entry Wrapper

Parameters

Different PX4 parameters become available depending on the build configuration set at the kconfig level. Any configuration listed also includes all parameters available in the configuration above it.

Vertiq IO Enabled

• VERTIQ_IO_CFG
  The serial port mapped to our module
• VERTIQ_BAUD
  The baud rate to use on the serial port we open and manage
• TARGET_MODULE_ID
  This is the module ID of the module that you would like to communicate with at the parameter level. All clients in the Vertiq Configuration Handler will be deleted and recreated with this module ID in their reinitialization
• TRIGGER_READ
  A boolean parameter that allows you to refresh responses from the module with module ID TARGET_MODULE_ID
• CONTROL_MODE
  This parameter is part of an EntryWrapper. This means that it acts as both a PX4 parameter and a Vertiq Client Entry. Specifically, this parameter interacts with the mode entry in the ESC Propeller Input Parser Client
• MAX_VELOCITY
  This parameter is part of an EntryWrapper that interacts with the velocity_max entry in the ESC Propeller Input Parser Client
• MAX_VOLTS
  This parameter is part of an EntryWrapper that interacts with the volts_max entry in the ESC Propeller Input Parser Client
• VERTIQ_MOTOR_DIR
  This parameter is part of an EntryWrapper that interacts with the sign entry in the ESC Propeller Input Parser Client
• VERTIQ_FC_DIR
  This parameter is part of an EntryWrapper that interacts with the flip_negative entry in the ESC Propeller Input Parser Client

IFCI Configuration Enabled

• VERTIQ_NUM_CVS
  The number of Control Values (discussed more here) that will be transmitted during each updateOutputs call
• DISARM_TRIGGER
  This specifies the behavior to be used when the mixer disarms. The choices are enumerated as the following
  • USER_MIXER_VALUE
    Specifies that the output control values should match the value set as the mixer’s disarmed value for each ESC channel
  • TRIGGER_MOTOR_DISARM
    Sends an explicit disarm command to all connected motors
  • COAST_MOTOR
    Sends an explicit coast command to all connected motors. When coasted, Vertiq ESCs stop sending control voltages allowing the motor to spin freely
  • SEND_PREDEFINED_VELOCITY
    Sends an explicit control velocity command to all connected motors
• ARMING_BEHAVE
  This specifies the behavior to be used when the mixer arms. The choices are enumerated as the following
  • FORCE_ARMING
    Sends an explicit arm command to all connected motors
  • USE_MOTOR_ARMING
    Uses each of the connected modules’ unique arming configurations to decide its own behavior based on the output throttle
• THROTTLE_CVI
  This parameter is part of an EntryWrapper that interacts with the throttle_cvi entry in the IQUART Flight Controller Interface Client
• TELEM_IDS_1
  This is a 32 bit bitmask with values 0-31 that allows users to easily select the module IDs from which they would like to receive telemetry. Combines with TELEM_IDS_2 to create a 64-bit bitmask of all possible Vertiq module IDs
• TELEM_IDS_2
  This is a 32 bit bitmask with values 32-62 that allows users to easily select the module IDs from which they would like to receive telemetry. Combines with TELEM_IDS_1 to create a 64-bit bitmask of all possible Vertiq module IDs

Pulsing Configuration Enabled

• PULSE_VOLT_MODE
  This parameter is part of an EntryWrapper that interacts with the pulsing_voltage_mode entry in the Pulsing Rectangular Input Parser Client
• PULSE_VOLT_LIMIT
  This parameter is part of an EntryWrapper that interacts with the pulsing_voltage_limit entry in the Pulsing Rectangular Input Parser Client
• X_CVI
  This parameter is part of an EntryWrapper that interacts with the x_cvi entry in the IQUART Flight Controller Interface Client
• Y_CVI
  This parameter is part of an EntryWrapper that interacts with the y_cvi entry in the IQUART Flight Controller Interface Client
• ZERO_ANGLE
  This parameter is part of an EntryWrapper that interacts with the zero_angle entry in the Voltage Superposition Client
• VELOCITY_CUTOFF
  This parameter is part of an EntryWrapper that interacts with the velocity_cutoff entry in the Voltage Superposition Client
• TORQUE_OFF_ANGLE
  This parameter is part of an EntryWrapper that interacts with the propeller_torque_offset_angle entry in the Voltage Superposition Client

Telemetry

With IFCI enabled, telemetry is requested from the Module IDs specified in the TELEM_IDS_1/2 in a round robin fashion. The data returned are described in the following struct:

Using the response, we fill in the esc_status publication’s esc_rpm, esc_voltage, esc_current, esc_power, and esc_temperature. The esc_armed_flags and esc_online_flags are set high for each ESC after the first successfully received telemetry response from each expected motor.

Non-Pulsing Flight Configuration Example with a Pixhawk 6c

In this example, our connected modules are set to a 921600 baud with module IDs 0, 26, 42, and 62 (configured using the IQ Control Center software)

1. Run boardconfig in order to turn on Vertiq IO and IFCI Configuration
2. Build and flash the firmware
3. Select Generic Quadcopter airframe and run sensor calibration
4. Set the VERTIQ_IO_CFG to TELEM 2 for this example. Save and reboot
5. Set the VERTIQ_BAUD parameter to 921600, and reboot
6. Connect the 4 modules to the Pixhawk in this configuration
   
7. Set VERTIQ_NUM_CVS to 4, TELEM_IDS_1 check 0 and 26, TELEM_IDS_2 check 42 and 62, and reboot
   In this case, we have 4 modules connected, each of which supports only the Throttle Control Value. In order for each of the modules to receive their own unique throttle command, we must send 4 Control Values (CVs)
8. Set TARGET_MODULE_ID to 0, and set THROTTLE_CVI to 0, CONTROL_MODE to Voltage, and MAX_VOLTS to 12. Do the same to all MODULE_IDS where each CVI is one greater than the next (TARGET_MODULE_ID 26 should have THROTTLE_CVI 1)
9. Use the Identify & Assign Motors tool to configure the ESCs correctly for their position
10. Ensure that each VERTIQ_MOTOR_DIR is correct for the module’s vehicle position. If not, change it to either 2D Clockwise or 2D Counter Clockwise to make it correct
11. For this example, I want to use Send Explicit Disarm as DISARM_TRIGGER so that we can hear the disarming sound
12. Configure your Radio, and you are ready to fly

Attached to this PR as well as below are a video of a hover flight as well as the log from it using the configuration described here.

vertiq_io_flight_sample.MOV
Link to Log