diff --git a/libraries/AP_Scripting/docs/docs.lua b/libraries/AP_Scripting/docs/docs.lua
index 7a5f34ac08..c7ca5c51e4 100644
--- a/libraries/AP_Scripting/docs/docs.lua
+++ b/libraries/AP_Scripting/docs/docs.lua
@@ -1536,6 +1536,22 @@ function MotorsMatrix:get_lost_motor() end
 ---@return boolean
 function MotorsMatrix:get_thrust_boost() end
 
+
+-- Sub singleton
+---@class sub
+sub = {}
+
+-- Return true if joystick button is currently pressed
+---@param index integer
+---@return boolean
+function sub:is_button_pressed(index) end
+
+-- Get count of joystick button presses, then clear count
+---@param index integer
+---@return integer
+function sub:get_and_clear_button_count(index) end
+
+
 -- desc
 ---@class quadplane
 quadplane = {}
diff --git a/libraries/AP_Scripting/examples/test_script_button.lua b/libraries/AP_Scripting/examples/test_script_button.lua
new file mode 100644
index 0000000000..c5b0c6f5ea
--- /dev/null
+++ b/libraries/AP_Scripting/examples/test_script_button.lua
@@ -0,0 +1,33 @@
+-- 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])))
+
+  -- count how many times the buttons were pressed in the last five seconds
+  local count = {}
+  for i = 1, 4 do
+    count[i] = sub:get_and_clear_button_count(i)
+  end
+
+  gcs:send_text(6, string.format("script button counts: %d, %d, %d, %d",
+      count[1], count[2], count[3], count[4]))
+
+  return update, 5000
+end
+
+return update(), 5000
diff --git a/libraries/AP_Scripting/generator/description/bindings.desc b/libraries/AP_Scripting/generator/description/bindings.desc
index 0d65248259..e1f4913d0a 100644
--- a/libraries/AP_Scripting/generator/description/bindings.desc
+++ b/libraries/AP_Scripting/generator/description/bindings.desc
@@ -461,6 +461,12 @@ singleton QuadPlane method in_assisted_flight boolean
 singleton QuadPlane method abort_landing boolean
 singleton QuadPlane method in_vtol_land_descent boolean
 
+include ../ArduSub/Sub.h depends APM_BUILD_TYPE(APM_BUILD_ArduSub)
+singleton Sub rename sub
+singleton Sub depends APM_BUILD_TYPE(APM_BUILD_ArduSub)
+singleton Sub method get_and_clear_button_count uint8_t uint8_t 1 4
+singleton Sub method is_button_pressed boolean uint8_t 1 4
+
 include AP_Motors/AP_MotorsMatrix.h depends APM_BUILD_TYPE(APM_BUILD_ArduPlane)||APM_BUILD_COPTER_OR_HELI
 singleton AP_MotorsMatrix depends APM_BUILD_TYPE(APM_BUILD_ArduPlane)||APM_BUILD_COPTER_OR_HELI
 singleton AP_MotorsMatrix rename MotorsMatrix