MAVLINKHUD
Download Android App Professional ArduPilot Ground Station
Full Parameter PDF

Overview

The BTN parameter group configures up to 4 physical push-buttons connected to the autopilot's GPIO pins. These buttons can be used to trigger flight mode changes, relay toggles, camera actions, or safety functions without needing an RC transmitter.

Note: This is for physical buttons on the drone, not buttons on your RC controller (see RCx_OPTION) or Joystick (see JS_BUTTON).

Key Concepts

1. Function Mapping (BTN_FUNCn)

Assigns an action to the button press.

  • Disabled: Do nothing.
  • Mode Change: Switch to Loiter, RTL, Auto, etc.
  • Camera: Trigger shutter.
  • Relay: Toggle a relay pin.
  • Arm/Disarm: Toggle arming state (dangerous).

2. Shift Functions (BTN_SFUNCn)

Allows a button to perform a different action if a designated "Shift" button is held down simultaneously.

Parameter Breakdown

  • BTN_ENABLE: Master switch.
  • BTN_PINn: GPIO/Servo pin number connected to the button.
  • BTN_FUNCn: Primary action.
  • BTN_OPTIONSn: Debounce logic and active high/low settings.

Integration Guide

  1. Hardware: Connect a momentary switch between a Signal Pin and Ground.
  2. Enable: Set BTN_ENABLE = 1.
  3. Map Pin: Set BTN_PIN1 to the servo rail pin number (e.g., 50 for AUX1).
  4. Set Function: Set BTN_FUNC1 to the desired action.
  5. Test: Press the button and check the GCS "Messages" tab for confirmation.

Developer Notes

  • Library: libraries/AP_Button
  • Polling: Buttons are polled at 10Hz-50Hz.

BTN1_FUNCTION

Default 0
Range 0 111

Joystick Button Function (BTN1_FUNCTION)

Description

BTN1_FUNCTION defines the "Primary Action" for the first button on your USB joystick or game controller.

This is extremely common in ArduSub and ArduBlimp applications. By assigning functions to specific buttons, you can fly the vehicle entirely from a joystick without needing a traditional RC transmitter.

Common Values

  • 0: None.
  • 1: shift. (Enables the BTN1_SFUNCTION for all other buttons).
  • 2: arm_toggle.
  • 3: arm.
  • 4: disarm.
  • 5-13: mode_X. (Sets a specific flight mode).
  • 21-27: mount/camera.
  • 31-36: lights.
  • 42-43: gain_inc/dec.

Tuning & Behavior

  • Default: 0.
  • Multiple Buttons: This parameter is replicated for every button on your controller (BTN2, BTN3, etc.).
View Source

BTN1_SFUNCTION

Default 0
Range 0 111

Joystick Button Shift-Function (BTN1_SFUNCTION)

Description

BTN1_SFUNCTION allows you to double the number of commands available on your joystick.

If any button on your controller is assigned to Function 1 (shift), then pressing this button (Button 1) while that shift button is held down will trigger the action defined here instead of the primary BTN1_FUNCTION.

View Source

BTN_DELAY

ms
Default 300
Range 0 3000

Button Delay (BTN_DELAY)

Description

This parameter is not found as BTN_DELAY in the main codebase. It appears to be a miscategorized OSD parameter.

View Source

BTN_ENABLE

Default 0
Range 0 1

Enable button reporting (BTN_ENABLE)

Description

Global switch to enable the button interface module. This allows physical buttons connected to the flight controller's GPIO pins to trigger auxiliary functions.

Tuning & Behavior

  • Default Value: 0 (Disabled)
  • Requires reboot to make other BTN_ parameters visible in the GCS.
View Source

BTN_FUNC1

Default 0

Button Pin 1 RC Channel function (BTN_FUNC1)

Description

Selects the action (Auxiliary Function) triggered when the button connected to PIN1 is pressed. Uses the same function IDs as RCx_OPTION.

View Source

BTN_FUNC2

Default 0

Button Pin 2 RC Channel function (BTN_FUNC2)

Description

Selects the action triggered when the button connected to PIN2 is pressed.

View Source

BTN_FUNC3

Default 0

Button Pin 3 RC Channel function (BTN_FUNC3)

Description

Selects the action triggered when the button connected to PIN3 is pressed.

View Source

BTN_FUNC4

Default 0

Button Pin 4 RC Channel function (BTN_FUNC4)

Description

Selects the action triggered when the button connected to PIN4 is pressed.

View Source

BTN_FUNCTION

Default 0
Range 0 100

Function for button (BTN_FUNCTION)

Description

This parameter assigns a Primary Function to a specific button on a connected USB Joystick or Gamepad (communicating via MAVLink). This allows for direct control of vehicle modes, camera triggers, relays, and servos from the controller.

The Mathematics

Enum Map.

The Engineer's View

Defined in libraries/AP_JSButton/AP_JSButton.cpp.

  • 0: Disabled.
  • 1: Mode Change (Manual/Stabilize).
  • ... (See Wiki for full list).

Tuning & Behavior

  • Default Value: 0 (Disabled)
  • Setup: Identify the button ID from your GCS/Driver, then set the corresponding BTN_FUNCTION parameter.
View Source

BTN_OPTIONS1

Default 0

Button Pin 1 Options (BTN_OPTIONS1)

Description

Advanced configuration for the first button, allowing for inverted logic or PWM signal detection instead of simple high/low voltage.

Tuning & Behavior

  • Default Value: 0
  • Bitmask:
    • Bit 0: PWM Input
    • Bit 1: InvertInput
View Source

BTN_OPTIONS2

Default 0

Button Pin 2 Options (BTN_OPTIONS2)

Description

Advanced configuration for the second button.

View Source

BTN_OPTIONS3

Default 0

Button Pin 3 Options (BTN_OPTIONS3)

Description

Advanced configuration for the third button.

View Source

BTN_OPTIONS4

Default 0

Button Pin 4 Options (BTN_OPTIONS4)

Description

Advanced configuration for the fourth button.

View Source

BTN_PIN1

Default -1

First button Pin (BTN_PIN1)

Description

Specifies the hardware pin connected to the first physical button.

Tuning & Behavior

  • Default Value: -1 (Disabled)
  • Common Values: 50-55 for AUXOUT 1-6 pins.
View Source

BTN_PIN2

Default -1

Second button Pin (BTN_PIN2)

Description

Specifies the hardware pin connected to the second physical button.

View Source

BTN_PIN3

Default -1

Third button Pin (BTN_PIN3)

Description

Specifies the hardware pin connected to the third physical button.

View Source

BTN_PIN4

Default -1

Fourth button Pin (BTN_PIN4)

Description

Specifies the hardware pin connected to the fourth physical button.

View Source

BTN_REPORT_SEND

s
Default 10
Range 0 3600

Report send time (BTN_REPORT_SEND)

Description

Determines for how long the flight controller will continue to broadcast a button state change message over MAVLink after the event occurs.

View Source

BTN_SFUNCTION

Default 0
Range 0 100

Function for button when the shift mode is toggled on (BTN_SFUNCTION)

Description

This parameter assigns a Secondary Function to a joystick button. This function is triggered instead of the primary BTN_FUNCTION when the user is simultaneously holding down the designated "Shift" button (see BTN_OPTIONS). This effectively doubles the number of commands available on a limited gamepad.

The Mathematics

Logic:
$$ \text{Action} = (\text{Shift Active}) ? \text{BTN\_SFUNCTION} : \text{BTN\_FUNCTION} $$

The Engineer's View

Defined in libraries/AP_JSButton/AP_JSButton.cpp.

Tuning & Behavior

  • Default Value: 0 (Disabled)
  • Example: Map Button 1 to "Mode Loiter" (primary) and "Mode RTL" (secondary/shifted).
View Source
Smart Battery Tags (BTAG) Buzzer Configuration (BUZZER)