Sending custom MAVLink commands with QGC

EliotBR · June 6, 2024, 2:02am

Hi everyone,

I’ve recently unearthed some little-known functionality in QGroundControl that allows configuring custom MAVLink commands to be sent to the vehicle, using either on-screen or joystick buttons!

While ArduSub comes with a number of joystick button functions built in, this can augment that, and also allows functionalities like controlling relays and setting PWM output values on other vehicle firmwares (like ArduRover on the BlueBoat!).

Fly View Actions (On-Screen Buttons)

Create an actions file, with the MAVLink commands you want to be able to send:
~/Documents/QGroundControl/CustomActions/FlyViewActions.json:

{
  "version":    1,
  "fileType":   "CustomActions",
  "actions":
  [
  {
    "label":        "Servo5 HIGH",
    "description":  "Sets servo 5 to a high PWM value",
    "mavCmd":       183,
    "param1":       5,
    "param2":       1900
  },
  {
    "label":        "Servo5 LOW",
    "description":  "Sets servo 5 to a low PWM value",
    "mavCmd":       183,
    "param1":       5,
    "param2":       1000
  },
  {
    "label":        "Relay1 ON",
    "description":  "Turns on relay 1",
    "mavCmd":       181,
    "param1":       0,
    "param2":       1
  },
  {
    "label":        "Relay1 OFF",
    "description":  "Turns off relay 1",
    "mavCmd":       181,
    "param1":       0,
    "param2":       0
  }
  ]
}

Enable Custom Actions in QGC’s Application Settings (access via the top left corner)
- This step is only required for QGC versions before the upcoming 4.5 release
Select the actions file from where you saved it

QGC-select-fly-view-actions1776×1318 341 KB
Access the actions when in Fly View, by clicking the “Action” button in the left sidebar, and pressing the relevant action button(s) in the popup at the bottom of the screen
- You may need to restart QGC after the actions file location is first configured
- The actions popup can be scrolled sideways to see additional actions, if more than a few are available

Joystick Button Functions

The process and syntax for this is changing from the existing stable releases, so there are two sets of instructions depending on which QGroundControl version you’re running.

QGC < 4.5

Instructions for existing stable versions

Create a JoystickMavCommands.json file:

The filename is hardcoded in QGC, so must match exactly

{
    "comment": "Joystick MAV commands",
    "version": 1,
    "commands": [
        {
            "id":       181,
            "name":     "Relay1 ON",
            "param1":   0.0,
            "param2":   1.0
        },
        {
            "id":       181,
            "name":     "Relay1 OFF",
            "param1":   0.0,
            "param2":   0.0
        }
    ]
}

Save it where your QGroundControl instance gets run from
- In Windows this is inside the folder where you installed it
  - e.g. C:\\Program Files\QGroundControl\JoystickMavCommands.json
- In MacOS this seems to be the root directory (/), which is read-only
  - This can be worked around by saving it in a memorable location (e.g. ~/Documents/QGroundControl/CustomActions/JoystickMavCommands.json), and then running QGC from in that folder via the Terminal:
```
%  cd ~/Documents/QGroundControl/CustomActions/
%  /Applications/QGroundControl.app/Contents/MacOS/QGroundControl
```
Configure your joystick buttons via the Vehicle Setup options
- You’ll need to scroll to the bottom of the actions dropdown to find your custom options
  
  QGC-4.3-custom-joystick-mavlink-commands1776×1318 416 KB

QGC >= 4.5

Instructions for current development and future stable releases

Create an actions file, with the MAVLink commands you want to be able to send:
~/Documents/QGroundControl/CustomActions/JoystickCustomActions.json:

{
  "version":    1,
  "fileType":   "CustomActions",
  "actions":
  [
  {
    "label":        "Servo5 HIGH",
    "description":  "Sets servo 5 to a high PWM value",
    "mavCmd":       183,
    "param1":       5,
    "param2":       1900
  },
  {
    "label":        "Servo5 LOW",
    "description":  "Sets servo 5 to a low PWM value",
    "mavCmd":       183,
    "param1":       5,
    "param2":       1000
  },
  {
    "label":        "Relay1 ON",
    "description":  "Turns on relay 1",
    "mavCmd":       181,
    "param1":       0,
    "param2":       1
  },
  {
    "label":        "Relay1 OFF",
    "description":  "Turns off relay 1",
    "mavCmd":       181,
    "param1":       0,
    "param2":       0
  }
  ]
}

Select the actions file from where you saved it, via the Application Settings in the top left corner

QGC-4.5-custom-joystick-actions1776×1318 349 KB
Access the actions when in Fly View, by clicking the “Action” button in the left sidebar, and pressing the relevant action button(s) in the popup at the bottom of the screen
- You may need to restart QGC after the actions file location is first configured
- The actions popup can be scrolled sideways to see additional actions, if more than a few are available
Configure your joystick buttons via the Vehicle Setup options
- You’ll need to scroll to the bottom of the actions dropdown to find your custom options
  
  QGC-4.5-custom-joystick-mavlink-commands1776×1318 416 KB

Relay Configuration

While the servo PWM commands typically provide direct control over flight controller servo output pins, the relay output pins are selectable from the available servo output pins, which needs to be set up in the autopilot parameters before the relay can be used.

When using a Navigator Flight Controller it is possible to see the state of the relay pins as 0/1 in the SERVO_OUTPUT_RAW MAVlink messages (e.g. via the MAVLink Inspector).

ArduSub (BlueROV2)

Allow the relevant servo pin to be used as a relay output, by setting its SERVOn_FUNCTION parameter to Disabled (0)
- “n” is the pin number being configured (e.g. 9)
Configure the relay number with the desired servo output pin, using the RELAY_PIN / RELAY_PIN2/3/4/5/6 parameter
Configure the joystick button function(s) as desired
- ArduSub provides built in relay_n_* functions for controlling relays 1-4
- The custom joystick button functions can be configured to allow control over relays 5 and 6, using the DO_SET_RELAY (181) and/or DO_REPEAT_RELAY (182) MAVLink commands
  - Note the relay numbering in the MAVLink message is 0-indexed, so relay 5 is index 4

ArduRover (BlueBoat)

Allow the relevant servo pin to be used as a relay output, by setting its SERVOn_FUNCTION parameter to GPIO (-1)
- “n” is the pin number being configured (e.g. 9)
Allow the relay number to be used as a servo output relay, by setting the RELAYn_FUNCTION to Relay (1), and rebooting the autopilot
- “n” is the relay number being configured (e.g. 1)
Connect the relay number to its servo output pin via the RELAYn_PIN parameter
Set up custom joystick button functions using the DO_SET_RELAY (181) and/or DO_REPEAT_RELAY (182) MAVLink commands, and configure the joystick button function(s) as desired

CA_BlueBoat · June 7, 2024, 3:55pm

This is great!

I would like to use a few joystick buttons to change the “WPNAV_SPEED” parameter during an autonomous mission with the Blueboat (either incrementally increase/decrease speed or slow medium fast on 3 buttons).
Looking through the Mavlink message lists, I cannot find anything that would change that parameter. do you have any advice?

Cheers

CA_BlueBoat · June 7, 2024, 4:32pm

I found the MAV_CMD_DO_CHANGE_SPEED message. Would something like this work:

  {
    "label":        "Slow Speed",
    "description":  "Travel at 1 m/s",
    "mavCmd":       178,
    "param1":       1,
    "param2":       1,
    "param3":       -1
  },
  {
    "label":        "Medium Speed",
    "description":  "Travel at 2 m/s",
    "mavCmd":       178,
    "param1":       1,
    "param2":       2,
    "param3":       -1
  },
  {
    "label":        "Fast Speed",
    "description":  "Travel at 3 m/s",
    "mavCmd":       178,
    "param1":       1,
    "param2":       3,
    "param3":       -1
  }

EliotBR · June 8, 2024, 12:54pm

Agreed! Definitely useful functionality to have, and to know about

Incremental controls require something to do the calculation with knowledge of the current state, and that generally needs to be built into the autopilot firmware (like we’ve done with the servo_n_inc/dec joystick button functions in ArduSub).

If there’s an appropriate MAVLink command then the three buttons approach should work with the steps I’ve outlined in this post

I believe that should work, at least until there’s a waypoint that sets a new speed target, or you go out of an autonomous control mode that supports speed regulation.

Note that for the joystick button functions, depending on your QGC version you may need to use the older format for specifying the MAVLink commands.

By the way, I’ve edited your comment to include a link to the MAVLink message in question, and also formatted your file snippet example as a pre-formatted text (/code) block, so the spacing is maintained. The How to Use the Forums post includes a section on what’s available for content formatting

clyde · June 8, 2024, 8:55pm

In ArduSub 4.5 BETA you can use joystick buttons to trigger actions in Lua scripts. You could write a Lua script that waits for a button press and then changes the WPNAV_SPEED parameter.

Here is a script showing how to access the joystick from inside Lua:

github.com

ArduPilot/ardupilot/blob/Sub-4.5/libraries/AP_Scripting/examples/test_script_button.lua

-- Test ArduSub script buttons

-- This will map the script buttons to the _shifted_ XBox controller buttons A, B, Z, Y:
-- param set BTN0_SFUNCTION  108
-- param set BTN1_SFUNCTION  109
-- param set BTN2_SFUNCTION  110
-- param set BTN3_SFUNCTION  111

function update()
  -- called every 5s

  -- show current status of the buttons
  local is_pressed = {}
  for i = 1, 4 do
    is_pressed[i] = sub:is_button_pressed(i)
  end

  gcs:send_text(6, string.format("is script button pressed? %s, %s, %s, %s",
      tostring(is_pressed[1]), tostring(is_pressed[2]), tostring(is_pressed[3]), tostring(is_pressed[4])))

This file has been truncated. show original

Here is a simple Lua script that changes a parameter:

github.com

ArduPilot/ardupilot/blob/Sub-4.5/libraries/AP_Scripting/examples/AHRS_switch.lua

-- switch between DCM and EKF3 on a switch

local scripting_rc1 = rc:find_channel_for_option(300)
local EKF_TYPE = Parameter('AHRS_EKF_TYPE')

function update()
   local sw_pos = scripting_rc1:get_aux_switch_pos()
   if sw_pos == 0 then
      EKF_TYPE:set(3)
   else
      EKF_TYPE:set(0)
   end
   return update, 100
end

return update()

Lua is pretty powerful, and the API is improving rapidly.

/Clyde

jdragano · July 12, 2024, 9:52pm

So as of today, I’m unable to recreate your advised method of creating Joystick button functions. Can you confirm that you’re still able to do so please as well as what version of QGC you’re running? I’m happy to downgrade QGC if needed at this point…

I’m running on Linux for reference. I’m fully able to create a FlyViewActions.json file and have the actions show up, but can’t recreate any part of your Joystick button functions.

tony-white · July 13, 2024, 7:05am

Hi @jdragano -
I’d suggest you review @EliotBR 's post again, and focus on the above or below QGC version 4.5 instructions depending on what you’re using! You do need to click the little arrow to expand these details…

jdragano · July 15, 2024, 1:20pm

Hi @tony-white while I appreciate that, I did in fact already attempt that after ‘clicking the little arrows to expand these details’ - had I not I wouldn’t be posting here, asking for help.

If anyone has constructive advice it would deeply appreciated…

tony-white · July 15, 2024, 9:11pm

Apologies @jdragano -
I only mentioned the sections under the arrows because it seemed you were unsure which instructions to follow in terms of your QGC version - both new and old are supported.
Have you not found the actions you added at the end of the list when configuring Joystick buttons?

jdragano · July 16, 2024, 1:24pm

No worries - apologies on my end as well.

But that’s correct, I don’t see the custom actions at the end of the list when configuring Joystick buttons (I do however get On-Screen Buttons with the FlyViewActions.json). I’m using QGC V4.4, running Ubuntu. I put it under ~/Documents/QGroundControl/CustomActions/
Here’s a more in detail look at what I have working/have tried for the joystick commands:

I tried saving JoystickMavCommands.json (exactly as given by Eliot) under ~/Documents/QGroundControl/CustomActions/ and running (a) the QGC.appimage from its location in Downloads while in the downloads directory and (b) navigating first to ~/Documents/QGroundControl/CustomActions/ and running the home/Downloads/QGC.appimage from there [essentially the Mac instructions bullet point]
Ubuntu seems to point to a .config file directory where QGC is ran from, so I attempted to also stick the json in that ‘install folder’, but that didn’t seem to work either

erkamtb · July 17, 2024, 2:22pm

i couldn’t find QGC 4.5 or any above? on the github page there is just 4.4

Still I can’t find the 4.5 or above version of qgc. Where is it?

EliotBR · August 1, 2024, 6:46am

Hi @jdragano,

I didn’t test on Ubuntu (which is why I didn’t include explicit instructions for it), but it sounds like it might have a similar situation to MacOS in terms of how and where it looks for the file.

You could try adding the file to your root directory (which you didn’t mention trying), but if that doesn’t work then it’s likely easiest to install a development release, in which case you can follow the >= 4.5 instructions, which allow you to just select where the file is in your filesystem from within QGC.

If you specifically need a stable build to work then you can try looking at QGC’s logs to see what kind of error(s) it’s giving about the custom actions, but determining the correct process for MacOS was a pain, and the Ubuntu one may be similarly annoying. You can of course wait until 4.5 is released as stable, but I’m not sure when that will be.

EliotBR · August 1, 2024, 6:53am

I mentioned in my original post that 4.5 is currently in development. There are daily build downloads available here, or if you want a specific time-point you can download the relevant Artifact from the GitHub Action for your operating system (e.g. here are the recent Windows builds).

Topic		Replies	Views
Controller <- MAVLink -> QgroundControl Minimal Example Blue Robotics Software	14	6443	May 21, 2018
Custome autopilo can not takeofft with QGroundControl and MAVLink V2? General Discussion	2	886	July 24, 2019
Sample code to run in QGC Blue Robotics Products	3	2579	January 23, 2018
qGroundcontrol through mavlink BlueBoat	11	73	November 5, 2024
Map a Joystick Button to Take a Picture QGroundControl pymavlink , sitl , simulate	1	1574	March 12, 2020

Community

BR Website

Software Docs

Autopilot Docs

BR and Beyond

Software

Sending custom MAVLink commands with QGC

Fly View Actions (On-Screen Buttons)

Joystick Button Functions

QGC < 4.5

QGC >= 4.5

Relay Configuration

ArduSub (BlueROV2)

ArduRover (BlueBoat)

Community

BR Website

Software Docs

Autopilot Docs

BR and Beyond

Software

Sending custom MAVLink commands with QGC

Fly View Actions (On-Screen Buttons)

Joystick Button Functions

QGC < 4.5

QGC >= 4.5

Relay Configuration

ArduSub (BlueROV2)

ArduRover (BlueBoat)

Related topics