How to simulate a pyro-cartridge launch of a UAV in ArduPlane SITL (XX-1 example)

[Mission-analyzer]

The task

XX-1 is launched by a pyro cartridge (angle about 45°). Three things are known: the altitude the aircraft is thrown to
(about 30 m), the speed it gains (about 37 m/s) and the cartridge action time (about 2 s). From these the acceleration
along the trajectory is about 18–19 m/s², and for a mass of 200–220 kg and an angle of 45° the thrust is about 5–6 kN and
the impulse about 11 kN·s (an estimate). How can such a launch be reproduced in ArduPlane SITL?

Which launches ArduPlane SITL provides

• An ordinary takeoff from the ground, like any aeroplane (VTOL layouts have their own takeoff modes, which are not
  considered here).
• Built-in launchers. They are enabled by a suffix in the model name (for example --model plane-catapult) and give a
  simple simulation: while the output of servo channel 7 is above 1700 µs (ArduPilot's own tests set channel 7 to
  2000 µs for this), an additional forward acceleration is applied to the aircraft for a fixed time:
  • -catapult is a catapult, 15 m/s² for 2 s (about 30 m/s ignoring friction);
  • -bungee is an elastic bungee cord, 7 m/s² for 4 s (about 28 m/s);
  • -throw is a hand throw, 25 m/s² for 0.4 s (about 10 m/s).

None of them is a pyro cartridge, so a home-made variant is needed for XX-1. What can be done is shown below.

Options

Option	What happens	Verdict
1. SITL's built-in launchers (-catapult, -bungee, -throw)	On the ground SITL adds a drag of 0.3·v, so the speed at the end of the launch is 24.5 / 19.3 / 9.9 m/s against a model stall speed of 30.2 m/s	the aircraft falls
2. Reproduce the shot itself: a script applies an impulse of about 5–6 kN at 45° to the model, step by step, for ~2 s	Realistic in time, but it is a separate model with parameters to be fitted; it is needed only if the launch itself is being studied	not chosen
3. X-Plane: the pyro cartridge is described by a JATO block (thrust, duration, angle)	Lets you describe the cartridge directly, but requires an installed X-Plane and an aircraft model in it	outside our task
4. Place the aircraft in the air in the "after the shot" state	Everything that happens after the launch (mission, modes, control) is tested as usual	chosen

What the chosen script does

ARM is the autopilot state in which it allows the motors and servos to work (the ARM button or command; the opposite is
DISARM). The script triggers on the transition "disarmed → armed".

• On ARM on the ground (altitude up to 3 m) it sets the simulator pose: altitude 30 m above the start point, speed 38 m/s
  along the current heading, flight path angle 9°, pitch 12°. Then it switches to AUTO (to FBWA if the aircraft has no
  mission).
• The method (sim:set_pose) is taken from ArduPilot's official example sim_arming_pos.lua. The parameters are
  constants at the top of the file rather than SIM_APOS_* parameters: parameters created by a script cannot be set in
  a defaults file, because they do not exist yet when it is loaded.
• The state corresponds to the end of the cartridge action: the aircraft has been thrown up to about 30 m and has gained
  about 37 m/s (38 m/s in the script). The flight path angle (9°) and the pitch (12°) are chosen close to equilibrium,
  with an angle of attack of about 3°.

Autopilot parameters

The script needs SCR_ENABLE=1 (enables scripting), AHRS_EKF_TYPE=10 and EK3_ENABLE=0 (and EK2_ENABLE=0). This is
what the ArduPilot developers themselves do in a test with a forced pose: the AHRS comes from the simulator, otherwise
the navigation filter sees a jump in position and velocity. The price: the navigation estimate follows the true state of
the simulator rather than the sensors.

Installation

Put the file into the scripts folder next to ArduPlane.elf (SITL loads every .lua file from it), set the
parameters above (for example through a --defaults file or in the console) and start SITL with your aircraft model. If
the parameters are set through --defaults, start SITL with -w, otherwise values stored by an earlier run will
override them. Connect, load a mission and press ARM: the aircraft appears in the air.

How it was checked

• Script logic: on a mock of the ArduPilot API, 21 checks (one launch per ARM, a new launch after DISARM and ARM, no
  launch when ARMed in the air, the FBWA fallback, waiting for a position, a set_pose error).
• The chosen state: on a copy of the SITL physics with a simple controller (pitch and throttle). The aircraft climbs from
  30 to 44 m and accelerates from 37 to 47 m/s in 30 s; there is no stall (minimum 36 m/s against a stall speed of
  30.2 m/s).
• Without control (open loop) the aircraft goes through a phugoid from this state and reaches the ground in about 10 s;
  this is expected, the autopilot (AUTO or FBWA) has to damp it.

Limitations

• The acceleration itself and launch failures are not reproduced: only what happens after the launch is tested.
• The launch state is tuned for XX-1; sim:set_pose works only in SITL.
• With SCR_ENABLE=1 SITL loads every .lua file from scripts/.

Adapting it to another aircraft

1. From the data of your own launch (the altitude the aircraft is thrown to, the speed it gains, the cartridge action
   time) determine the state of the aircraft at the end of the cartridge action. Take the flight path angle and the
   pitch close to equilibrium (angle of attack 2–4°).
2. Put the values into the constants at the top of the script and choose the mode after the launch.
3. Make sure the launch speed exceeds the model's stall speed with a margin (here 38 against 30.2 m/s).

The script

License: GPL-3.0-or-later (the script follows the approach of ArduPilot's official example).

-- SPDX-License-Identifier: GPL-3.0-or-later
--[[
  xx1_launch.lua -- starts XX-1 in the "after the pyro-cartridge launch" state in ArduPlane SITL.

  The real XX-1 is launched by a pyro cartridge (about 45 deg): within ~2 s it accelerates to
  ~37 m/s and is thrown up to ~30 m. The model has no thrust of its own that could reproduce such
  an acceleration in SITL (and on the ground SITL adds a drag of 0.3*v), so the launch itself is
  not modelled: at arming the aircraft is placed directly in the air in the "after launch" state.

  The method is the same as in ArduPilot's official example libraries/AP_Scripting/examples/
  sim_arming_pos.lua: sim:set_pose() on the transition to "armed". The parameters here are not
  SIM_APOS_* but the constants below: parameters created by a script cannot be set in a defaults
  file (they do not exist yet at the moment the file is loaded).

  The state corresponds to the end of the cartridge action (~2 s after the launch): the aircraft
  has been thrown up to ~30 m and has gained ~37 m/s. The flight path angle and the pitch are
  chosen close to equilibrium (angle of attack about 3 deg).

  REQUIRES these parameters: SCR_ENABLE=1, AHRS_EKF_TYPE=10, EK3_ENABLE=0.
  Without the simulator's AHRS the navigation filter sees a jump in position and velocity.
  Put the file into the SITL/scripts/ folder (next to ArduPlane.elf).
--]]

-- ===== state after the launch (edit here if needed) =====
local LAUNCH_ALT_M     = 30.0   -- altitude above the arming point, m
local LAUNCH_SPEED_MS  = 38.0   -- speed along the flight path (relative to the ground), m/s
local LAUNCH_PATH_DEG  = 9.0    -- flight path angle above the horizon, deg
local LAUNCH_PITCH_DEG = 12.0   -- pitch, deg (about 3 deg above the path angle, i.e. the angle of attack)
local LAUNCH_MODE      = 10     -- mode after the launch: 10 = AUTO
local FALLBACK_MODE    = 5      -- if AUTO is refused (no mission loaded): 5 = FBWA
local MAX_ARM_ALT_M    = 3.0    -- act only on the ground (not when re-armed in the air)

local launched = false          -- the aircraft was already placed in the air for the current arming

local function launch()
    local loc = ahrs:get_location()
    if not loc then
        return false                       -- no position yet -- try again on the next cycle
    end

    local pitch = math.rad(LAUNCH_PITCH_DEG)
    local yaw = ahrs:get_yaw_rad()         -- keep the current heading: the aircraft flies where it was pointing
    local gamma = math.rad(LAUNCH_PATH_DEG)

    local quat = Quaternion()
    quat:from_euler(0.0, pitch, yaw)

    -- set_pose takes the velocity in the EARTH NED frame (north, east, down)
    local vel = Vector3f()
    vel:x(LAUNCH_SPEED_MS * math.cos(gamma) * math.cos(yaw))
    vel:y(LAUNCH_SPEED_MS * math.cos(gamma) * math.sin(yaw))
    vel:z(-LAUNCH_SPEED_MS * math.sin(gamma))

    loc:alt(loc:alt() + math.floor(LAUNCH_ALT_M * 100.0 + 0.5))   -- altitude is in centimetres

    local gyro = Vector3f()                -- zero angular rate

    if not sim:set_pose(0, loc, quat, vel, gyro) then
        gcs:send_text(4, "XX-1 launch: sim:set_pose failed")
        return true                        -- do not retry forever
    end
    gcs:send_text(6, string.format("XX-1 launch: %.0f m, %.0f m/s", LAUNCH_ALT_M, LAUNCH_SPEED_MS))

    if not vehicle:set_mode(LAUNCH_MODE) then
        vehicle:set_mode(FALLBACK_MODE)
    end
    return true
end

local function update()
    if not arming:is_armed() then
        launched = false                   -- the next arming will launch the aircraft again
        return update, 100
    end
    if launched then
        return update, 100
    end

    local d = ahrs:get_relative_position_D_home()    -- down, m; ~0 on the ground
    if d and d < -MAX_ARM_ALT_M then
        launched = true                    -- already in the air: leave everything alone
        return update, 100
    end

    if launch() then
        launched = true
    end
    return update, 100
end

gcs:send_text(6, "XX-1 launch script loaded")
return update, 1000