jsbsim-service/service/README.md

Local Flight Simulation Service

Offline mock service for the first milestone.

Run

npm run service

The default URL is:

http://127.0.0.1:4317

Endpoints

• GET /health
• GET /aircraft
• POST /trim
• POST /simulate
• POST /cancel

Coordinate and Heading Conventions

• Local position is [east, up, north] in meters.
• True heading 0 deg points north.
• Clockwise heading is positive.
• Counter-clockwise heading is negative.

Rates

• sampleRateHz controls the output sample frequency returned to the web client.
• integrationRateHz controls the internal JSBSim integration frequency and defaults to 120.
• The web client currently requests sampleRateHz: 30 and integrationRateHz: 120.
• trim: false skips pre-simulation trim. This is useful for F-22 maneuver research because the bundled F-22 model can run from initial conditions even when longitudinal trim fails.

The mock service currently supports:

• straight
• climb
• descent
• level-turn
• control-script
• cobra

Maneuver Research Path

This project treats special maneuvers as reusable control-input studies:

1. Use control-script for raw elevator/aileron/rudder/throttle timelines.
2. Build named maneuver templates, such as cobra, on top of those timelines.
3. Compare mock output against the JSBSim backend.
4. Improve or replace aircraft XML models when high-alpha/post-stall data is not credible.

control-script parameters:

{
  "timeline": [
    { "t": 0.0, "elevator": 0, "aileron": 0, "rudder": 0, "throttle": 0.85 },
    { "t": 0.5, "elevator": 0.8, "aileron": 0, "rudder": 0, "throttle": 1.0 },
    { "t": 1.6, "elevator": 0, "aileron": 0, "rudder": 0, "throttle": 1.0 }
  ]
}

cobra is currently an experimental template. It is useful for plumbing and visualization, but physical credibility depends on the selected JSBSim aircraft model having high-alpha and post-stall aerodynamic tables.

The default F-22 research path uses f22cobra-jsbsim, a project-local copy of the bundled F-22 model with manual TVC command support. The current stable near-cobra baseline uses the closed-loop Cobra controller:

{
  "aircraftId": "f22cobra-jsbsim",
  "durationSec": 5,
  "initialState": { "position": [0, 3000, 0], "velocityMps": 120, "headingDeg": 0 },
  "trim": false,
  "maneuver": {
    "type": "cobra",
    "parameters": {
      "controlMode": "closed-loop",
      "pullDurationSec": 0.7,
      "recoveryDurationSec": 2.0,
      "targetAlphaDeg": 80,
      "pitchRateLimitDegS": 80,
      "maxElevatorCmd": -0.45,
      "recoveryElevatorCmd": 0.65,
      "pullTvcCmd": -0.05,
      "recoveryTvcCmd": 0.85,
      "throttleCmd": 1,
      "speedbrakeCmd": 0
    }
  }
}

This baseline reaches roughly 70-72 degrees alpha in the current model, keeps peak pitch rate around 120-125 deg/s, and recovers to low alpha by the end of the run. Higher-alpha open-loop settings can still be tested with "controlMode": "open-loop", but they tend to deep-stall or over-rotate with the current F-22 aerodynamic tables.