Interface control document

1. Identification

2. Scope

This document defines the SimConnect data-definition and subscription contract the module establishes with the simulator, how the two simulator variants are selected and what differs between them, the connection and reconnect lifecycle, and the complete mapping from each registered simulation variable to the field it is published into.

The module is read-only with respect to simulator state. It registers data definitions, subscribes to data and to two system events, and writes nothing back into the simulator. The only file it writes is the remote connection configuration described in section 7.

Section 9 is the normative mapping. Section 10 lists the places in this revision where the value written into a field does not match that field’s defined quantity, scale or unit. Both sections are statements about revision 69d794b, not about the SimConnect API.

3. Interface inventory

4. Simulator variant selection

There is no runtime simulator detection and no setting that chooses a simulator. The variant is fixed by which of the two packages is installed. Each package ships a different module assembly that supplies its own backend, its own vendor wrapper and its own native client directory.

Everything else is shared. Both variants register the same ten built-in definition groups, request them at the same periods, and run the same mapper and the same event detector. The only capture differences are the two Prepar3D data sources in sections 9.11 and 9.12.

Both variants are registered as ModuleType.System with ModuleStartupType.SystemStartup, so they connect and hold a connection from HEAT Capture startup, independently of whether a capture session is running.

5. IF-CMSIMCONNECT-01 Simulation variable subscription

5.1 Transport and addressing

5.2 Connection lifecycle and reconnect

InitialiseModule creates the client, subscribes to its disconnect and active-state events, makes one synchronous connect attempt, and starts the silence timer. This runs inside the SDK StartupTimeout, 5 seconds by default.

On the simulator’s open acknowledgement the backend raises Opened on the pump thread, and the client then, in this order: registers the ten built-in definition groups, starts the ten data requests, subscribes to the Sim and Pause system events, registers each simulator-specific data source, and logs SimConnect connected to {App} (SimConnect {Major}.{Minor}) with the application name and SimConnect version the simulator reported.

StartCapture resets the event detector and sets the simulation tick counter to zero. It does not touch the connection or the cache. EndCapture does nothing.

Reconnect is driven from two triggers. A failed connect attempt logs SimConnect connection attempt failed - will retry as a warning and starts the reconnect loop. A disconnect, meaning either the simulator’s quit message or an exception on the pump thread, starts the same loop.

The loop waits ReconnectIntervalMs, default 5000 ms, disposes the current backend, and connects again. A failure logs SimConnect reconnect attempt failed at debug level and doubles the delay, capped at 30000 ms. A success logs SimConnect reconnected and ends the loop. The loop is unbounded in attempts and only ends on success, on cancellation, or on module disposal. The backoff is not reset by a later success, because each new loop starts from ReconnectIntervalMs.

Because the backend is recreated on every attempt, the definition groups, data requests, system event subscriptions and data sources are all re-registered on each successful reconnect, and the snapshot cache from before the disconnect is retained rather than cleared.

Disposal cancels the reconnect loop, disposes the silence timer, and disposes the client. Backend disposal cancels the pump, joins the pump thread with a 2 second timeout so the native handle is not freed while a dispatch is in progress, then disposes the wrapper and swallows any exception from it.

5.3 Authentication

None, in either mode. Local mode inherits whatever access control the simulator’s own SimConnect endpoint applies to local clients. Remote mode is a plain IPv4 connection to RemoteHost on RemotePort; the generated configuration carries no credential, and the module presents none.

5.4 Wire format

Each definition group is a SimConnect data definition built by adding its variables one at a time, then binding a sequentially laid-out managed struct to the group. Struct packing is 1, character set is ANSI, and the field order in the struct must equal the order the variables were added. Meaning is therefore entirely positional: nothing in the payload identifies which variable a field came from.

Simulator-specific sources use request and definition identifiers at or above 100 so they cannot collide with the built-in groups. The Prepar3D weapons group uses 100 and the Prepar3D display probe uses 120.

Requested units are expressed through a fixed neutral enumeration, and each value maps to exactly one SimConnect unit string:

Data types are FLOAT64, INT32, STRING32 and STRING256. String variables are registered with the None unit, because SimConnect rejects a non-null units string on a string type.

Every arriving payload is boxed by the backend and stored, under a lock, into a per-group slot in the client’s snapshot cache. Each new payload replaces the previous one for that group; no history is kept.

5.5 Delivery cadence

Delivery is simulator-driven. Eight groups are requested per visual frame, so their arrival rate is the simulator’s render rate. AircraftInfo and ATC are requested once per second. The Prepar3D weapons group is per visual frame and the Prepar3D display probe is once per second.

Publication is not tied to delivery. The module reads the cache at the SDK Interval cadence, 1000 ms by default, so at a 60 Hz render rate roughly 59 of every 60 arrivals of a visual-frame group are overwritten before they are ever read. This is by design for state, but it also means transitions are detected only against the values latched at successive publication cycles, not against every value the simulator delivered.

6. IF-CMSIMCONNECT-02 System event subscription

Two named SimConnect system events are subscribed on every connect: Sim and Pause. Their payload is treated as a boolean, non-zero meaning true.

The module keeps both flags and derives one combined active state, defined as running and not paused. It raises a change only when that combined state flips.

The simulator’s quit message also clears both flags, without raising a combined-state change.

A separate silence timer runs on a 1 second period, independent of these events. When StopOnSilence is set, a session is started, the client is connected, and the time since the last payload of any kind is at least SilenceThreshold, it logs {Time}s of silence detected - stopping session and asks the host to stop the session. The logged value is the seconds component of SilenceThreshold, so a threshold expressed as a whole number of minutes logs as 0s.

7. IF-CMSIMCONNECT-03 Remote connection configuration file

When RemoteHost is empty or null, no file is written and config index 0 is used. When RemoteHost has a value, the module overwrites SimConnect.cfg in the application base directory, beside the module binaries, with exactly this content and then connects with config index 1:

[SimConnect.1]
Protocol=IPv4
Address=<RemoteHost>
Port=<RemotePort>
MaxReceiveSize=4096

The protocol, the section index and the 4096-byte receive size are fixed in code. The file is rewritten on every connect attempt, including every reconnect attempt, and is never deleted.

8. IF-CMSIMCONNECT-04 Frame publication and data model reference

8.1 Entity identity

The identity is derived from the cached title, not from the fallback name, so a frame published before the first AircraftInfo payload is named Unknown Aircraft with id 0. The hash is computed from scratch on every publication cycle and is stable across processes and sessions for a given title.

8.2 Frame envelope

Each publication cycle produces one SimulationFrame with one EntityState.

The only timestamp a consumer can rely on for state is therefore the SDK’s own envelope value, DataPacket.TimestampUnixMs, taken when the payload is wrapped. See the Module SDK ICD for that envelope.

8.3 Publication preconditions

Nothing is published, and the cycle returns no frame, in either of these cases: the client is null or reports not connected, or the Core group has never delivered a payload. The module does not publish a seeded or zeroed frame.

Once the Core group has delivered once, a frame is published every cycle even if the connection later drops mid-cycle, and every group other than Core is optional. An absent group means its components are omitted, except where section 10 records a group whose absence produces a published value rather than an omission.

Component presence is therefore:

An unknown aircraft type publishes neither the fixed-wing nor the rotary-wing components, and is not logged.

8.4 Events

Events are edge-triggered against the previous publication cycle’s value. Detector state is recreated by StartCapture, with initial values of not stalling, not overspeeding, on the ground, and engine not running.

There is deliberately no overspeed_warning_off: the detector is given a null falling-edge label for that transition, so a cleared overspeed warning produces no event.

Because the initial state assumes on the ground with the engine off, a session started with the aircraft already airborne or already running publishes airborne or engine_running on the first cycle even though nothing changed at that instant.

The detector also contains a threshold-event helper that nothing calls, so no ThresholdEvent is ever published by this module. G-force is captured and published as state only.

Prepar3D adds the discrete combat events in section 9.11, drained once per cycle from the weapons source. They carry the same entity id and timestamp as the frame’s other events, not the time the transition was observed on the pump thread.

9. Simulation variable to published field mapping

Conversion factors used below, as defined in the mapper:

Every value is narrowed from the transported double to float when written. “Not published” means the variable is registered and cached but no published field is derived from it.

9.1 Core group

Present in every published frame.

9.2 Engine group

Only engine 1 is registered. A multi-engine aircraft publishes one engine component describing its first engine.

9.3 Fixed-wing group

Published only when the aircraft type resolves to fixed-wing.

FWADataComponent.indicated_altitude and FWADataComponent.kohlsman_setting exist in the schema and are never populated by this module. That is the other half of SIM-01.

FWAInputComponent also carries five fields sourced from other groups:

9.4 Rotary-wing group

Published only when the aircraft type resolves to rotary-wing.

engine_torque_limit is not populated.

9.5 Landing gear group

No WheelComponent is populated, and allow_steering, parking_brake_available, gear_max_airspeed, hydraulic_pressure, lock_on and is_damaged are not set.

9.6 Aircraft identity group

9.7 Avionics group

Mode resolution is strictly first-match in the priority order shown, so only one lateral and one vertical mode is ever reported even when the simulator has several engaged.

Backcourse hold is a label-only override: when it is engaged the label becomes backcourse regardless of the other lateral variables, while active_lateral_mode still reports whichever of approach, nav or heading hold matched. A consumer that reads the enum and the label together will see them disagree in that case. There is no backcourse value in the lateral mode enumeration.

9.8 Propulsion control group

A rotary-wing or unknown-type aircraft publishes nothing at all from this group, because its only published destination is the fixed-wing input component.

9.9 Fuel system group

Nine ResourceStoreEntry rows are published unconditionally whenever the group is cached, whether or not the aircraft has the corresponding tank. A tank the aircraft does not have reports quantity 0, which is indistinguishable from a real empty tank.

Within each row, the quantity variable becomes current_quantity unconverted, and the level variable is multiplied by 100 and carried as an extra_data entry keyed fill_level_percent. Every row also sets resource_type to RESOURCE_TYPE_FUEL and unit to RESOURCE_UNIT_GALLONS, and sets max_quantity to 0, resource_type_label to an empty string and unit_label to an empty string.

The remaining variables in the group:

9.10 ATC identity group

The transponder value is registered with the number unit but formatted on the assumption that the simulator returned a binary-coded value, so that each hexadecimal digit is one squawk digit. The module does not validate that assumption, and it does not reject a value whose hexadecimal rendering contains digits 8 or above, which cannot occur in a real octal squawk. A code that needs more than four hexadecimal digits is rendered at its natural width rather than truncated.

9.11 Prepar3D weapons group

Registered and requested per visual frame by the Prepar3D variant only. This group populates no component; it produces only discrete events. Per-station variables are registered for stations 1 to 16 and marshalled as fixed 16-element arrays; the simulator reports zero for stations beyond the aircraft’s actual station count.

On a target change the source emits, in this order, a TargetTrackingEvent with state Released, sensor_or_lock_type fcs and reason changed for the previous target when that was non-zero, then a TargetTrackingEvent with state Locked and sensor_or_lock_type fcs for the new target when that is non-zero. Target ids are read as unsigned 32-bit values before being widened, so a negative identifier from the simulator becomes a large positive entity id.

A weapon-selection change emits StateChangedEvent with state set to weapon_selected: followed by the reported weapon type. A selection clearing to an empty string emits nothing.

Transitions are detected on the pump thread at visual-frame rate and queued, then drained once per publication cycle, so this source does not lose transitions between cycles the way the shared detector does. The queue is unbounded.

The first payload after each connect establishes the baseline and emits nothing.

9.12 Prepar3D display probe group

Registered and requested once per second by the Prepar3D variant only. All eight variables are carried verbatim as AircraftDisplayStateComponent.extra_data entries, and the first four also feed the derived page labels.

Two display entries are published, always both and always with these fixed identifiers, and soi_display_id is always an empty string:

active_page is therefore a derived power and degradation label, not a page name. SimConnect exposes generic simulation variables only; the aircraft-local gauge variables that a custom multi-function display uses for its page and sensor-of-interest state are not reachable this way, so no real page identity is available to publish. On registration the source records this as an information-level log line.

The probe also logs its values once on the first payload and again on every change.

9.13 Values published without a source variable

These fields are written on every applicable frame from a constant, not from the simulator. A consumer cannot distinguish them from a measured value.

SimConnect exposes no transfer-path, dump-rate or fuel-flow variable in the set this module registers, so the fuel process values above have no available source. The armed autopilot modes have no source either: the module registers only engaged states.

10. Mapping defects in this revision

These are properties of revision 69d794b, not of SimConnect or of the HEAT schema. SIM-01 is the recorded audit finding; the remaining rows are observations from the same reading of this revision and carry no finding id.

AircraftAvionicsComponent.active_lateral_mode_label disagreeing with active_lateral_mode under backcourse hold, described in 9.7, is a schema limitation rather than a mapping error: the lateral mode enumeration has no backcourse value.

11. Units and conventions

Values are passed through without range validation. The authority for the meaning of each simulation variable is the simulator vendor’s own SimConnect documentation; this module does not define or constrain it.

12. Error behaviour

The debug-level handling of protocol exceptions is the significant one. Because definition layout is positional, a rejected variable name silently changes what every following field in that group means, and the only report of it is a debug log line.

13. Configuration affecting the interfaces

Nothing in the settings changes which simulation variables are registered, which units are requested, or which periods are used. Those are fixed in code, as is the 500 ms pump wait, the 2 second pump join on disposal, the 1 second silence-timer period, the 30000 ms reconnect cap, the 4096-byte remote receive size, and the 16-station cap in the Prepar3D weapons source.

The generic SDK settings also apply. Interval is the publication cadence and is re-read every cycle; it does not change the simulator’s delivery rate. See Manage capture modules for those, and the Module SDK ICD for the lifecycle and envelope this module runs inside.

14. Compatibility and versioning

There is no protocol version negotiation. The module logs the application name and SimConnect version the simulator reports on open, and then proceeds identically whatever those values are. No version gate, capability check or feature test exists.

Compatibility rests on three assumptions, none of which is verified at runtime:

• Every registered variable name is accepted by the simulator with the requested unit string. A rejection is only debug-logged, and because layout is positional the group’s remaining fields shift and are misattributed.
• The vendor wrapper and the native client in the package match the installed simulator. The two packages are not interchangeable and the module cannot detect being paired with the wrong simulator.
• The managed wrappers are mixed-mode assemblies and cannot load into a collectible assembly load context. A host using a custom module load context must fall back to the non-collectible default context.

Variable coverage is a fixed list. Variables the simulator supports but the module does not register are absent; there is no way to extend the set through configuration.

15. Security considerations

The local interface is the simulator’s own SimConnect endpoint on the same workstation, with no authentication and no encryption. Any local process able to reach that endpoint can subscribe to the same data.

Remote mode increases the exposure: an unauthenticated, unencrypted IPv4 connection whose endpoint the module writes in cleartext into SimConnect.cfg beside its own binaries, rewritten on every connect attempt and never removed. Anyone able to read the module directory learns the remote host and port; anyone able to write it can redirect the module to another host. Treat remote mode as suitable only for a trusted, isolated network segment.

Captured content is aircraft state and, on Prepar3D, weapons employment. The aircraft title, ATC identity and transponder code identify the simulated aircraft rather than the operator, but a session still associates a named user with a training exercise. Restrict access to captured sessions according to the deployment’s own data-handling policy.

16. Conformance

1. Install the package matching the simulator on that workstation and confirm the native client is present in the variant’s simconnect directory. Confirm on startup that the log records SimConnect connected to with the expected application name and a SimConnect version.
2. With the simulator loaded into a flight, confirm one entity appears, named with the aircraft title, and that its id is stable across a restart of HEAT Capture with the same aircraft.
3. Confirm the aircraft type gate: with a fixed-wing aircraft, the three fixed-wing components are present and the rotary-wing component absent; with a helicopter, the reverse. With an aircraft whose category is none of the five recognised values, confirm neither set is published.
4. Verify SIM-01 directly. Read the simulator’s altimeter setting and its indicated altitude, then confirm the published barometric altitude equals the altimeter setting in millibars and not the indicated altitude in metres. Retain that trace as the before state for any correction.
5. Verify the scale defects in section 10 on a single frame: extend the gear fully and confirm gear extension publishes 1; deploy spoilers to a partial detent and confirm spoiler position publishes 0.
6. Confirm the first-frame boolean behaviour: with a fixed-wing aircraft, capture the first frames after a connect and check whether autothrottle, afterburner and reverse thrust are published as engaged before the avionics and propulsion groups have arrived.
7. Pause the simulation and confirm the session stops when StopOnSimPaused is set, then resume and confirm it starts again when StartOnSimRunning is set.
8. Close the simulator while capturing. Confirm the sim-quit warning, then restart the simulator and confirm reconnection without restarting HEAT Capture, and that the reconnect log line appears.
9. On the Prepar3D variant, arm the weapon system, fire from a station, dispense a countermeasure and change the fire-control target. Confirm one event per transition and confirm the countermeasure event carries an empty name.
10. If remote mode is used, confirm SimConnect.cfg is written beside the module binaries with the expected host and port, and that its presence is acceptable under the deployment’s own handling rules for network configuration.

17. Revision history

HEAT Capture team. Last updated 2 October 2026.