PX4-Autopilot
PX4-Autopilot copied to clipboard
PX4
Vertiq-PX4 Integration Implementation
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)
- Run boardconfig in order to turn on Vertiq IO and IFCI Configuration
- Build and flash the firmware
- Select Generic Quadcopter airframe and run sensor calibration
- Set the VERTIQ_IO_CFG to TELEM 2 for this example. Save and reboot
- Set the VERTIQ_BAUD parameter to 921600, and reboot
- Connect the 4 modules to the Pixhawk in this configuration
- 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)
- 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)
- Use the Identify & Assign Motors tool to configure the ESCs correctly for their position
- 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
- For this example, I want to use Send Explicit Disarm as DISARM_TRIGGER so that we can hear the disarming sound
- 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
@vertiq-jordan need to run 'make format' and commit the format changes. It looks like the module.yaml is failing the validation check. I added some inline comments but basically the yaml params need default values (some have already, but not all)
Also there is a flash over flow on fmuv5x:
arm-none-eabi/bin/ld: region FLASH_AXIM' overflowed by 377 bytes`
It appears some of the module.yaml short descriptions are too long:
{'parameters': [{0: [{'definitions': [{'CONTROL_MODE': [{'default': ['required field'], 'description': [{'short': ['max length is 70']}]}], 'DISARM_VELO': [{'description': [{'short': ['max length is 70']}]}], 'MAX_VELOCITY': [{'default': ['required field'], 'description': [{'short': ['max length is 70']}]}], 'MAX_VOLTS': [{'default': ['required field'], 'description': [{'short': ['max length is 70']}]}], 'PULSE_VOLT_LIM': [{'default': ['required field'], 'description': [{'short': ['max length is 70']}]}], 'PULSE_VOLT_MODE': [{'default': ['required field']}], 'TARGET_MODULE_ID': [{'default': ['required field']}], 'TELEM_IDS_1': [{'description': [{'short': ['max length is 70']}]}], 'THROTTLE_CVI': [{'default': ['required field']}], 'TORQUE_OFF_ANGLE': [{'default': ['required field'], 'description': [{'short': ['max length is 70']}]}], 'TRIGGER_READ': [{'default': ['required field'], 'description': [{'short': ['max length is 70']}]}], 'VELOCITY_CUTOFF': [{'default': ['required field']}], 'VERTIQ_FC_DIR': [{'default': ['required field'], 'description': [{'short': ['max length is 70']}]}], 'VERTIQ_MOTOR_DIR': [{'default': ['required field']}], 'X_CVI': [{'default': ['required field'], 'description': [{'short': ['max length is 70']}]}], 'Y_CVI': [{'default': ['required field'], 'description': [{'short': ['max length is 70']}]}], 'ZERO_ANGLE': [{'default': ['required field']}]}]}]}]} Exception: Validation of /__w/PX4-Autopilot/PX4-Autopilot/src/drivers/actuators/vertiq_io/module.yaml failed
This pull request has been mentioned on Discussion Forum for PX4, Pixhawk, QGroundControl, MAVSDK, MAVLink. There might be relevant details there:
https://discuss.px4.io/t/px4-sync-q-a-may-22-2024/38872/1
Looks like there's a build problem with FMUv6X-RT
https://github.com/PX4/PX4-Autopilot/actions/runs/10492660066/job/29064789041?pr=22892#step:8:118
CMake Error at src/drivers/actuators/vertiq_io/CMakeLists.txt:48 (add_library):
Cannot find source file:
iq-module-communication-cpp/src/generic_interface.cpp
Tried extensions .c .C .c++ .cc .cpp .cxx .cu .m .M .mm .h .hh .h++ .hm
.hpp .hxx .in .txx
CMake Error at src/drivers/actuators/vertiq_io/CMakeLists.txt:48 (add_library):
No SOURCES given to target: iq_communication
CMake Generate step failed. Build files cannot be regenerated correctly.
Error: /__w/PX4-Autopilot/PX4-Autopilot/build/px4_fmu-v6xrt_allyes is not a directory
make: *** [Makefile:227: px4_fmu-v6xrt_allyes] Error 1
Looks like there's a build problem with FMUv6X-RT
https://github.com/PX4/PX4-Autopilot/actions/runs/10492660066/job/29064789041?pr=22892#step:8:118
CMake Error at src/drivers/actuators/vertiq_io/CMakeLists.txt:48 (add_library): Cannot find source file: iq-module-communication-cpp/src/generic_interface.cpp Tried extensions .c .C .c++ .cc .cpp .cxx .cu .m .M .mm .h .hh .h++ .hm .hpp .hxx .in .txx CMake Error at src/drivers/actuators/vertiq_io/CMakeLists.txt:48 (add_library): No SOURCES given to target: iq_communication CMake Generate step failed. Build files cannot be regenerated correctly. Error: /__w/PX4-Autopilot/PX4-Autopilot/build/px4_fmu-v6xrt_allyes is not a directory make: *** [Makefile:227: px4_fmu-v6xrt_allyes] Error 1
Whoops. Our submodule was pointing to an ssh link. Fixed it, and it seems like all of the tests pass now.
This pull request has been mentioned on Discussion Forum for PX4, Pixhawk, QGroundControl, MAVSDK, MAVLink. There might be relevant details there:
https://discuss.px4.io/t/px4-sync-q-a-sep-11-2024/40625/3
This pull request has been mentioned on Discussion Forum for PX4, Pixhawk, QGroundControl, MAVSDK, MAVLink. There might be relevant details there:
https://discuss.px4.io/t/px4-sync-q-a-sep-11-2024/40625/1