Aircraft Config (e3x.json)

Every aircraft can carry its own e3x.json, a small JSON file that tells the E3X what is installed in that panel. It sets how many displays and ADAHRS (air data, attitude and heading reference system) units the panel has. It says whether there is an engine interface, a standby instrument or an autopilot controller, and which IFR navigators sit beside it. It also sets which radios the E3X controls and which trim and flap position strips the PFD (primary flight display) shows. It holds the V-speeds on the airspeed tape and any engine-gauge reference values.

The E3X reads the file each time the aircraft loads. You can set up a Cessna with one display and a twin with two once each, and they just work.

The file also marks an aircraft as carrying the E3X. With X-Plane, the E3X starts only when an aircraft with an e3x.json loads, and stops when one without it loads. A file that declares no equipment list gets the default install. That install is one display, one ADAHRS and one engine interface, with every radio controlled by the E3X.

Editing it on the unit

You do not have to open the file at all. Menu → Setup → Config in the E3X edits it, on four tabs:

• Radios — which radios the E3X controls (COM 1/2, NAV 1/2, audio panel, transponder), each Off or On.
• LRUs — line-replaceable units, the equipment list as eight slots: ADAHRS 1 and 2, Engine Unit, Standby Instrument, AP Controller, AP Servos, Navigator 1 and 2. AP Servos offers None, GSA 28 Roll+Pitch or GSA 28 Roll+Pitch+Yaw. The number of displays is not a slot: it follows the E3X displays you actually have up in X-Plane (3D-panel screens or open pop-out windows). Each box also has a Power dropdown saying which aircraft electrical bus feeds it. Each display (GDU 1 (PFD), GDU 2 (MFD)) has a row with just that dropdown; see The power block.
• Engine — the engine-display fields (cylinders, fuel capacity, manifold pressure, probe counts, and so on) plus a “<GAUGE> Limits” row per gauge the aircraft draws. Every field offers Auto, which leaves it out of the file so the E3X detects it from the aircraft. Its row shows the detected value behind it, for example “Auto (4)”, and the keypad’s Clear sets a row back to Auto. A Limits row opens a popup with the gauge’s band edges (scale min/max, colored bands, redlines), each defaulting to Auto. The fields write the engine section; the Limits popups write the gauge_limits block, and MENU → Restore Defaults under a popup clears that gauge.
• Airframe — these rows, in order:
  • The map’s Aircraft Icon (Auto, or one of the icons). The icon writes aircraft_icon.
  • Which of the PFD’s Trim/Flap Position strips the aircraft has: Flaps, Elevator Trim, Aileron Trim and Rudder Trim, each Off or On. All four start On; switch off the ones your aircraft does not have. The toggles write trim_flap.
  • The V-speeds: the ten airspeed-tape reference speeds (Vso, Vs1, Vfe, Vno, Vne, Va, Vx, Vy, Vg, Vr), plus Sink Rate at Vg right after Vg. Each shows its Auto value (“Auto (163)”) until you pin it (set a fixed value) on the keypad. Vfe grays out while Flaps is Off. The speeds write vspeeds.
  • The AP Profile picker and an AP Status line. The status line says what the autopilot mapping (how the E3X drives this aircraft’s autopilot) is doing. The profile picker writes autopilot.

The E3X writes each change to the aircraft’s e3x.json at once and applies it within a second or two, with no reload needed. The status line under the rows names the file it is writing, for example “Saved to Cessna 172 SP/e3x.json”. When the file holds more than one model’s entry, the line also names the entry you are editing (see Variants).

Restore Defaults (MENU) clears the current tab’s section from the file, and some keys stay behind. The LRUs tab removes install and leaves the power block, so the default boxes then run on its buses. The Airframe tab clears the AP profile choice and leaves an inline definition and disable_modes / enable_modes. The Engine tab leaves the hand-edited keys that have no row (gauges, cas, engine_index, ff_unit, temp_units, gravity_feed).

The page knows where the aircraft lives through X-Plane, so it writes the same file the plugin reads. Sometimes no aircraft folder is known: with the built-in demo and replay sources, or in the first moments after the sim starts. The page then writes settings/e3x.json under the E3X data folder instead, and says so.

The LRUs tab shows the inventory as the eight slots above. A hand-written file can hold more than the slots can show (a third ADAHRS, a third navigator, a wiring-only box, a custom sources list).

Editing a slot changes only that slot’s boxes. A box no slot owns stays untouched. A box that still fits its slot keeps its id and every setting (its sources and power list included). A re-typed box keeps everything the slot does not decide. Setting a slot to None removes its boxes.

Where the file lives

• The file’s exact name is e3x.json (lower case).
• It sits in the aircraft’s own folder, beside its .acf file (X-Plane’s aircraft file), for example X-Plane 12/Aircraft/Laminar Research/Cessna 172 SP/e3x.json.
• Only the aircraft you are flying (X-Plane’s user aircraft) is read.
• The file must be smaller than 256 KiB.

The companion X-Plane plugin looks for the file whenever an aircraft loads and hands it to the E3X, which applies it within about ten seconds. The file therefore takes effect when the E3X runs with X-Plane through the plugin. The built-in demo and replay sources read settings/e3x.json under the E3X data folder instead (the file the Config page writes for them).

Creating it

You rarely need to write the file from scratch:

• The setup wizard’s aircraft page (Windows and Linux) lists the aircraft in your X-Plane folder. Select the ones that carry the E3X, and the wizard writes an e3x.json into each from a suggested starting template. The page shows the template beside each aircraft, and aircraft that already have a file say so. You need to close X-Plane while the wizard writes the files. Run the wizard again to add more aircraft; the finish page lists every file it wrote.

• The generated Cessna 172 SP E3X (e3x-core install xplane --no-copy --cockpit, or e3x-core install aircraft) builds an E3X-equipped 3D-panel aircraft from your stock 172 with its own e3x.json already in place.

• From the command line, for any aircraft folder:

  e3x-core install aircraft-config --dir "<the aircraft's folder>" [--install <template>] [--variant <acf>]

  --dir is the folder that holds the .acf. --install picks one of the shipped templates. Without it, a stock X-Plane aircraft the E3X recognizes gets its recommended install, bus wiring included (see the power block). Any other aircraft gets the c172_e3x boxes with no bus wiring.

  --variant writes only the entry for one .acf in the folder, and keeps the file’s other entries. Give it the file name without .acf, or "*" for every .acf without its own entry.

  The command refuses to run while X-Plane is running, and warns if the folder has no .acf. It rewrites the "*" entry of an existing e3x.json, and tells you when it does. On a stock folder with no other template named, it also rewrites each model entry the template table seeds. It keeps each rewritten entry’s power wiring and any other model’s entry; see Variants.

A written file carries a _comment line pointing back to this page. The E3X ignores it, like any key it does not know.

Applying a hand edit

A change made on the Config page applies by itself. A change made by hand in an editor is read only when an aircraft loads. Save the file and then reload the aircraft in X-Plane (Developer → Reload the Current Aircraft, or load another flight with it). You do not need to restart X-Plane: about ten seconds after the reload the E3X is running on the new file. Do not hand-edit the file while also changing settings on the Config page: the page rewrites the whole file from what it last read.

Variants: one config per aircraft model

Some aircraft folders hold more than one model. X-Plane 12’s stock Cessna 172 SP folder has Cessna_172SP.acf (steam gauges, KAP 140 autopilot), Cessna_172SP_G1000.acf and Cessna_172SP_seaplane.acf, and they all share this one file. So everything in the file sits inside a variants object, one complete config per model:

{
  "variants": {
    "Cessna_172SP_G1000": { "name": "Cessna 172 SP G1000 E3X", "install": { ... }, ... },
    "*":                  { "name": "Cessna 172 SP E3X",       "install": { ... }, ... }
  }
}

• A key is the .acf file name without .acf. The loaded aircraft uses its own entry, else "*". With neither, the file does not apply to it.
• Entries never combine: the one in force is the whole config. To change something for every model, change it in every entry.
• Setup → Config and Setup → Units edit the entry the loaded aircraft is using, and only that one. If the file has no entry for the aircraft, the first edit creates one for it.
• When the file holds more than one entry, the Config page’s status line names the entry you are editing after the file. For example: “Saved to Cessna 172 SP/e3x.json (Cessna_172SP_G1000)”, or “(other models)” for the "*" entry. With a single entry it names only the file.
• Most aircraft need only "*". The installer writes that entry and keeps any others.
• A file written before variants existed, with the sections at the top level, still works as a single "*" entry. The first edit on the unit rewrites it in this layout.

The format

The file is one JSON object holding the variants object above:

{
  // One complete config per aircraft model in this folder (see "Variants").
  // "*" is every model without an entry of its own; most files have only it.
  "variants": {
    "*": { "name": "Cessna 172 SP E3X", "install": { ... }, "radios": { ... } }
  }
}

Each entry is itself one JSON object with the keys below. Every section is optional and independent. The E3X ignores a broken section on its own (see Errors) while the others still apply.

Key	Type	What it does
name	string	The aircraft’s name. Also used as the install’s name. On its own it changes nothing.
install	object	The equipment list: {"lrus": [ ... ]}, with an optional name (by default the entry’s name). Without it, the default install applies.
power	object	Which aircraft bus feeds each box, see below. Sits beside install, never inside it. Without it, the E3X models no bus power.
radios	object	Which radios the E3X controls, see below. Without it, all of them.
trim_flap	object	Which trim and flap position strips the PFD shows, see below. Without it, all four.
vspeeds	object	The airspeed tape’s V-speeds in knots, see below. Without it, every speed is Auto.
ap_native	object	Autopilot coupling overrides, see below.
autopilot	object	How the E3X drives this aircraft’s autopilot, see below. Without it, Auto (detected).
aircraft_icon	string	The map’s own-aircraft icon: sport_plane, high_wing, low_wing, tail_dragger, twin, canard, jet or helicopter. Without it, Auto (picked from the aircraft).
units	object	This aircraft’s Setup → Units display-unit choices, written by that Setup page. The keys are temperature (F, C), baro_pressure (inhg, mb, hpa), weight (lb, kg), fuel (usgal, l, lb, kg), fuel_economy (sm_gal, nm_gal, km_l, l_100km). Without it, the first of each list (fuel: lb on an aircraft that states its fuel flow in lb/hr).
Engine fields	various	Engine-display settings at the top level of the entry, see below.
gauge_limits	object	Per-gauge scale ends, bands and redlines, see below.

The equipment list (install.lrus)

Each entry is one box (LRU) in the panel:

Field	Type	Required	Default	Rules
id	string	yes	—	Unique in the file, and must end in a digit: adahrs1, not adahrs.
type	string	yes	—	One of the types below.
role	string	no	"primary"	"primary" or "standby".
eis_coupled	boolean	no	false	Accepted only on types that can supply engine data; meaningful on GSU73 (see below).
sources	list of strings	no	[]	Advanced: the signal groups this box supplies, replacing the type’s own. Each one of attitude, heading, air_data, position, engine, fuel, electrical, airframe.
axis	string	GSA28 only	—	The servo’s axis: "roll", "pitch" or "yaw". Required on a GSA28, rejected on every other type; one servo per axis.
power	list of strings	no	every declared bus	The buses feeding the box, by the names the power block declares. Any one live bus powers it. Never empty: leave the key out for every bus.

Types:

type	What it is
GDU460	The E3X display. With X-Plane the number in use follows the displays you have up (3D-panel screens or pop-out windows). The count in the file is the fallback for the demo and replay sources.
GSU25	ADAHRS (attitude, heading, air data).
GSU73	ADAHRS; with "eis_coupled": true it also carries the engine data (no separate engine interface needed).
GEA24	Engine interface.
G5	Standby instrument (attitude, heading, air data). Normally "role": "standby".
GMC507	Autopilot mode controller. Its presence is all that matters.
GSA28	Autopilot servo (GSA 28), with an axis. The autopilot lives in the servos, so a servo’s power decides whether the autopilot can fly.
GTN650, GTN750	External IFR navigator (GTN 650 / GTN 750).
GNS430, GNS530	External IFR navigator (GNS 430W / GNS 530W).
GPS175, GNC355, GNX375	External IFR navigator (GPS 175 / GNC 355 / GNX 375).
G1000	X-Plane’s G1000 as the navigator source.
GMU11, GTX, GAD29, GPS20A	Wiring-only boxes: magnetometer (GMU 11), transponder (GTX), data concentrator (GAD 29), GPS receiver (GPS 20A). They let the file list the whole panel and its bus wiring but feed no instrument of their own.

What the list controls:

• ADAHRS count. GSU25, GSU73 and G5 are ADAHRS-class. With two or more of them in the list, a standby G5 included, the E3X offers the sensor source picker, as the real unit does. A G5 with "role": "standby" is the instrument the E3X reverts to when no ADAHRS data is available.
• Engine interface (GEA24, or a GSU73 with "eis_coupled": true). This names the box that carries the engine, fuel, electrical and airframe signals. It matters for the failure model. The Failures menu lists the box, and failing it (there, or with the --fail drill) blanks every gauge it feeds at once. Leaving the engine interface out does not hide the engine display; the gauges still show what the sim reports.
• Autopilot controller (GMC507): with one installed, the autopilot’s basic modes keep running if you lose the PFD (its display failed or its window gone). They are AP, LVL, ROL, PIT and ALT, run from the controller’s own keys, as on the real unit. Without one, a PFD loss disconnects the autopilot, as an attitude loss does. Nothing else reads it. The default install has no controller; the stock-aircraft templates and the generated Cessna 172 SP E3X do.
• Autopilot servos (GSA28, one per axis). A failed or unpowered roll or pitch servo makes the autopilot unavailable. A yaw servo belongs to the yaw damper, which then survives the loss of the other two. Without declared servos none of this applies.
• Navigators appear in the flight-plan source picker under the names in the table.
  • Each navigator’s unit number comes from the digits at the end of its id (gns530_1 is unit 1, gns430_2 is unit 2). An id without trailing digits takes its position in the list instead.
  • You declare the box, not the software behind it. When a RealityXP or TDS navigator of the same model is running in the sim, the E3X couples the declared unit to it. Failing that, the same family counts: any GTN for a declared GTN. Otherwise the unit uses X-Plane’s own flight plan, unit 1 the pilot’s, unit 2 the copilot’s.
  • G1000 always couples to X-Plane’s own plan. A navigator you do not list gets no feed, even if its plugin is running. The Panel Integration guide covers coupling.

The power block (power)

A real installation wires every box to one or two aircraft buses (the electrical power lines). The power block says which X-Plane bus feeds which box. A dead bus or the avionics master switch then takes down exactly the boxes wired to it. The block sits in the entry beside install, never inside it. Without it, the E3X models no bus power for the aircraft at all.

"power": {
  "buses": {"bus1": {"xp_bus": 0}, "bus2": {"xp_bus": 1}, "avn": {"xp_bus": 0}},
  "avionics_master": ["avn"]
}

Field	Required	Meaning
buses	yes	A name per bus, each reading one X-Plane electrical bus: xp_bus 0 to 5 (bus 1 to bus 6). Two names can read the same X-Plane bus.
avionics_master	no	The bus names that are live only while the avionics master switch is on.
nominal_v	no	The system voltage (14, 28). Accepted for compatibility; the E3X does not use it (the power thresholds are the same for a 14 V and a 28 V system).

Each box then names its inputs with "power": [...] in install.lrus. Any one live input powers it, like the real units’ dual power inputs. Every declared bus feeds a box with no power list.

A box whose inputs are all dead behaves as if it had failed. Its instruments red-X and the displays revert, a display goes dark, and an unpowered GMC 507’s keys stop working. An unpowered roll or pitch servo makes the autopilot unavailable. Restoring power makes it available again, but nothing re-engages it. A short sag, such as an engine crank, does not cycle the panel.

The avionics master. X-Plane’s avionics master does not change the bus voltage, so “behind the avionics master” is a second name for the same bus, listed in avionics_master. Take a one-bus aircraft with buses {"bat": {"xp_bus": 0}, "avn": {"xp_bus": 0}} and "avionics_master": ["avn"]. The displays and ADAHRS are on ["bat", "avn"] and the servos on ["avn"]. It loses the autopilot and keeps the screens when the avionics master goes off.

A display’s power list should match the bus wired to its cockpit object in the aircraft. While the companion plugin reports that display on or off, the E3X uses that report for the bus. A backup battery is part of the aircraft (a second battery or an essential bus in X-Plane): name that bus.

Errors drop only the wiring. A bus name that buses does not declare is an error, and so is a box power list without a power block. So are a power block inside install, an empty power list and an xp_bus outside 0 to 5. Your boxes stay, and the E3X models no bus power until you fix the file. The E3X logs the reason, and the Config page’s status line reads “e3x.json power wiring ignored: fix the file”.

Stock aircraft ship with recommended wiring. The installer recognizes X-Plane’s stock aircraft by their .acf names and writes each one’s recommended install, power block included. Any other aircraft gets boxes with no wiring (add the block yourself, or use the Config page, to opt in):

Aircraft	Template	Buses	Displays, ADAHRS, engine unit	Autopilot controller and servos
Cessna 172 SP (SP, seaplane)	c172_stock	2	Bus 1 + Bus 2 (GDU 2: Bus 2 (avionics))	Bus 1 (avionics)
Cessna 172 SP G1000	c172_g1000_stock	2	Bus 1 + Bus 2	Bus 1 (avionics)
Cessna 172 SP E3X (generated)	c172_e3x	2	Bus 1 + Bus 2 (GDU 2: Bus 1)	Bus 1 (avionics)
Van’s RV-10	rv10	1	Bus 1	Bus 1 (avionics)
Cirrus SR22	sr22	3	Bus 1 + Bus 3 (main + essential)	Bus 2 (avionics)
Beechcraft Baron 58	baron58	1	Bus 1	Bus 1 (avionics)
Beechcraft King Air C90B	c90b	3	Bus 1 + Bus 2	Bus 2 (avionics)
Cirrus Vision SF50	sf50	2	Bus 1 + Bus 2	Bus 1 (avionics)
Cessna Citation X	citation_x	3	Bus 2 + Bus 3	Bus 2 (avionics)
Lancair Evolution	lancair_evo	2	Bus 1 + Bus 2	Bus 1 (avionics)

Each also fits a G5 standby on any bus. The shipped templates table lists every box each template installs and the .acf the installer seeds it for.

Re-running the installer rewrites the entry from the template but keeps your wiring. An existing power block stays exactly as it is, and boxes you did not have then come in on every bus. Every box you had keeps its own power list. The template replaces the rest of the entry.

When the kept wiring no longer fits the new box list, the installer warns that the E3X will ignore it until you fix the file. An unreadable file has no wiring to keep, and the installer replaces it whole. Deleting the power block opts a stock aircraft out of bus power, but a re-install undoes that. With no block to keep, the installer writes the recommended one again.

On the unit. Setup → Config → LRUs gives each box a Power dropdown beside its type. Each display (GDU 1 (PFD), GDU 2 (MFD)) gets a row with just that dropdown. The choices follow the aircraft’s bus count. Until X-Plane reports it, the choices are buses 1 and 2, or up to the highest bus the file’s power block names:

• Any bus — no power list; every declared bus feeds the box.
• Bus N — X-Plane bus N.
• Bus N (avionics) — bus N, live only while the avionics master is on.
• Bus N + Bus M — a box with two power inputs (essential + main).

A choice uses a bus you already declared with the same X-Plane bus and avionics-master gating, whatever its name. On the Cessna 172 SP E3X, “Bus 1 (avionics)” writes your avn. The page adds a bus only when no such bus exists. It names the new bus bus1 to bus6, or avn1 to avn6 for a bus behind the avionics master. It lists the buses it added in the block’s "_managed" list.

The page only ever removes those, once no box lists them. If you edit one by hand, it becomes yours. The page never changes or removes your own buses, _comment, nominal_v or any other key. Buses you named yourself show by what they read (avn on bus 1 behind the master shows “Bus 1 (avionics)”). Wiring none of the choices can say shows “Custom” until you pick something else.

If the aircraft had no power block, the page creates one. While some box is on Any bus, choosing “Bus N (avionics)” then also adds an ungated bus N. That keeps those boxes from ending up behind the avionics master.

Setting every box back to Any bus removes a block the page created (and with it bus power modeling); a block you wrote stays. Changing a box’s type keeps the block and every box’s power list. While the status line says the E3X ignores the wiring, the Power dropdowns read “Invalid” and refuse edits until you fix the file.

The radios block (radios)

One boolean per radio function; a missing key means true:

Key	Radio
com1, com2	The comm transceivers.
nav1, nav2	The VOR/LOC receivers.
audio	The audio panel.
xpdr	The transponder.

true means the E3X shows and controls that radio. false removes it everywhere at once: its CNS-bar cell, its menu tile, its frequency-load targets and (for NAV) its CDI source. It suits a panel where another unit owns that box. The Config page’s Radios tab writes this block; see Radio control enables.

Trim and flap strips (trim_flap)

The PFD’s Trim/Flap Position indicators (PFD Setup → Trim/Flap Position) show a strip per control the aircraft has. A flap strip (F) and an elevator trim strip (E) sit side by side, with an aileron trim bar (A) beneath them. When fitted, a rudder trim bar (R) sits back to back under the aileron one. This block says which the aircraft has:

Key	Value	Effect
flaps	true / false	The flap position strip.
elevator_trim	true / false	The elevator (pitch) trim strip.
aileron_trim	true / false	The aileron (roll) trim bar.
rudder_trim	true / false	The rudder (yaw) trim bar.

A key left out (or set to true) shows the strip; the scale draws with no pointer until the sim reports a value. false hides it even though the sim streams a value.

X-Plane publishes an aileron and a rudder trim for every aircraft, including ones with no such control in the cockpit. It has no way of saying which aircraft really have one, so the E3X does not guess. A stock Cessna 172 shows all four strips until you switch Aileron Trim and Rudder Trim off. The Config page’s Airframe tab writes this block.

V-speeds (vspeeds)

The airspeed tape’s reference speeds, in knots. Each key is optional. A speed you leave out is Auto. That is the sim’s authored design speed where it publishes one (X-Plane’s Plane Maker airspeed markings), otherwise the E3X’s built-in default.

Key	Speed
vso	Stall, landing configuration (bottom of the white arc).
vs1	Stall, clean (bottom of the green arc).
vfe	Max flap extended (top of the white arc).
vno	Max structural cruising (green → yellow).
vne	Never exceed (the red line and barber pole).
va	Maneuvering.
vx	Best angle of climb.
vy	Best rate of climb.
vg	Best glide (also drives the glide range ring).
vr	Rotate.
sink_rate	Sink rate at Vg, in feet per minute (the glide model’s second input). Auto: worked out from Vg at a 10:1 glide.

Pinning vne raises the top of the tape to match. The Config page’s Airframe tab writes this block. Each speed shows the Auto value it would use (“Auto (163)”). Vfe grays out while Flaps is Off, and the keypad’s Clear puts a speed back to Auto.

The autopilot block (autopilot)

The E3X’s own AFCS (automatic flight control system) is the autopilot’s brain; the simulator’s autopilot is the servo it drives. The E3X drives stock X-Plane aircraft through the sim’s standard autopilot, and they need no configuration. Some add-ons replace the autopilot with their own. For example, the JustFlight/Thranda PA-28 line’s S-TEC ignores the standard engage switch, and the sim sounds its disconnect tone when the E3X presses it. The autopilot block says how the E3X drives this aircraft.

Key	What it does
profile	A bundled mapping by name: xplane_native (X-Plane’s own autopilot, the default) or thranda (the JustFlight/Thranda PA-28 line). "auto", or no block at all, detects.
definition	An inline mapping for an aircraft nobody has mapped yet (below). When both are present, definition wins.
disable_modes	AFCS modes to gray out on this aircraft, on top of whatever mapping is in force.
enable_modes	Modes a mapping disabled that you want back. Wins over disable_modes.

"autopilot": {"profile": "thranda"}

Auto-detection. With no profile (or "auto"), the E3X looks for an add-on’s own autopilot in the running sim and uses X-Plane’s autopilot when it finds none.

It never picks a mapping from the aircraft’s name alone. The name only orders the candidates, and a check of the add-on’s own datarefs (X-Plane’s named data values) confirms. The Thranda mapping, for instance, needs the Thranda plugin in the aircraft’s folder. A Thranda-built aircraft whose plugin has another name can pin it with {"profile": "thranda"}.

On the unit. Setup → Config → Airframe has two rows for this block:

• AP Profile — Auto (showing what it detected, for example “Auto (X-Plane autopilot)”), then each bundled mapping. The list marks a mapping not yet verified in flight with “(draft)”. An inline definition shows as “File (<its name>)” and locks the row: you can edit a definition only in the JSON.
• AP Status — what the mapping is doing:
  • Ready (followed by the modes the aircraft’s own autopilot flies, e.g. “Ready HDG VS ALT IAS”) when the mapping loaded, X-Plane’s own included.
  • Resolving while detection waits on the sim. The aircraft flies on X-Plane’s autopilot meanwhile.
  • Native (Web API unreachable) / Native (aircraft path unknown) when it waits on an answer that is not coming yet.
  • Native alone before any mapping has resolved, or on a source with no mapping to resolve.
  • Draft: N values to fill while a TODO: remains.
  • N errors: run apmap validate when a reference is wrong.
  • Not writable: needs a profile when the aircraft’s autopilot refused the E3X’s engage.
  • Unsafe writes on for a definition with unsafe_writes.

Graying a mode the airframe lacks. If an aircraft genuinely cannot fly a mode (a roll-only autopilot with no pitch axis, say), list it in disable_modes. Mode keys: hdg, trk, nav, appr, ias, alt, vs, vnav, lvl.

A disabled mode is gray and inert on the AFCS window and the GMC 507 bezel. This is the one case where a mapping limits the E3X rather than extending it. Use it only for a mode the airframe truly does not have. A block holding only these keys still auto-detects, then applies them:

"autopilot": {"disable_modes": ["vs"]}

"autopilot": {"enable_modes": ["ias"]}

The bundled thranda mapping grays IAS for the whole JustFlight/Thranda PA-28 line (none has a stock FLC, or flight-level change mode) but keeps VS mode. The Archer III’s S-TEC 55 has it, and the E3X flies the Arrow’s and Warrior II’s hidden VS fine. To match a bare stock panel on one of them, add "disable_modes": ["vs"] to that aircraft’s e3x.json.

Inline definitions

An aircraft nobody has mapped yet gets a definition. Three shapes cover every autopilot seen so far.

(1) Custom readback over the stock autopilot. The aircraft’s autopilot is X-Plane’s, but its panel lamps live on the aircraft’s own datarefs (Laminar’s King Air C90B and Baron 58). Keep the stock actuation with "extends": "xplane_native" and point only the status reads at those datarefs:

"autopilot": {"definition": {
  "name": "my_c90b", "label": "King Air C90B", "schema": 1, "extends": "xplane_native",
  "master":   {"status": {"read": {"xp_dataref": "laminar/c90/lighting/annun/fcp_ap_engaged"}}},
  "channels": {"hdg": {"status": {"read": {"xp_dataref": "laminar/c90/autopilot/switch/hdg_pos"}}}}
}}

(2) The aircraft’s own autopilot, engaged by a dataref write. The autopilot is a plugin whose engage is a writable dataref (the Thranda S-TEC, IXEG, ToLiss):

"autopilot": {"definition": {
  "name": "my_archer_stec", "label": "Archer S-TEC 55X", "schema": 1,
  "vendor_prefixes": ["thranda/"],
  "master": {
    "engage":    {"write": {"xp_dataref": "thranda/autopilot/Power"}, "value": 1},
    "disengage": {"write": {"xp_dataref": "thranda/autopilot/Power"}, "value": 0},
    "status":    {"read":  {"xp_dataref": "thranda/autopilot/Power"}, "eq": 1}},
  "channels": {
    "hdg": {"engage": {"command": {"xp_command": "sim/autopilot/heading"}},
            "status": {"read": {"xp_dataref": "sim/cockpit2/autopilot/heading_status"}, "gt": 0.5},
            "target": {"write": {"xp_dataref": "sim/cockpit2/autopilot/heading_dial_deg_mag_pilot"}, "unit": "deg"}}}
}}

(3) The aircraft’s own autopilot, driven by commands. Its buttons are X-Plane commands with a status dataref each (the vFlyteAir GFC 500):

"autopilot": {"definition": {
  "name": "my_gfc500", "label": "GFC 500", "schema": 1, "vendor_prefixes": ["VFLYTEAIR/"],
  "master": {
    "engage": {"command": {"xp_command": "VFLYTEAIR/GFC500/cmd_GFC500_AP"}}, "toggle": true,
    "status": {"read": {"xp_dataref": "VFLYTEAIR/GFC500/APEngaged"}}},
  "channels": {
    "hdg": {"engage": {"command": {"xp_command": "VFLYTEAIR/GFC500/cmd_GFC500_HDG"}},
            "status": {"read": {"xp_dataref": "VFLYTEAIR/GFC500/HDGModeEngaged"}}}}
}}

The pieces:

• master — the autopilot itself: engage, disengage, status, and available (below).
• Channels — what the sim side can operate: hdg, vs, alt, ias and roll. Each has an engage action, an optional status read and an optional target, the dial the E3X writes (heading bug, selected VS, altitude or speed). The dial is a dataref with a unit of deg, ft, fpm, kt, m or mps, so the E3X converts for you. The E3X reserves rol, pit, nav, apr, lvl, fd and yd: it ignores them with a warning, which AP Status counts as an error. Any other channel name is an error.
• Actions — write a value; set or clear bits ({"set": mask} or {"clear": mask}); or fire a command (held for hold_s seconds when given). An action can also be a sequence of actions with a settle_s pause. "toggle": true marks a push-on/push-off button; it defaults to true on a channel and false on master. A toggling channel engaged by a command needs a status to check first, or "toggle": false.
• Status — reads a dataref and compares it with one of eq, ne, gt, ge, lt, le, bit or in. With none, a value above 0.5 is true.
• References — {"xp_dataref": "..."} (optionally with an "index") or {"xp_command": "..."}.
• extends fills everything you leave out from a bundled mapping.
• Advanced keys, rarely needed, on a channel: disengage, armed, detect, semantics, captures_current, capture_band, hold_ref. On a target: clamp, round, scale, offset, readback. On master: fd_mode, fd_on, fd_off, fd_status, yd_on, yd_off, yd_status, engage_grace_s, engage_retry_s, inhibit_on_ground. On the definition: modes.lateral, modes.vertical, select, status. On an action: transport.

The E3X flies a mode with no channel of its own through the puppet channel for its axis: hdg for lateral and vs for vertical. You can change these with "puppet": {"lateral": ..., "vertical": ...}. That is how the stock autopilot works too, so a mapping extends what the E3X can do rather than limiting it. If the mapping has no puppet channel for that axis either, nothing moves the servos. The mode is then flight-director only: the cue shows and you fly it.

A write to any dataref or command outside X-Plane’s autopilot namespaces needs its prefix in "vendor_prefixes" (as above), or "unsafe_writes": true.

Which shape is my aircraft? If the aircraft’s own autopilot engages when the E3X drives the stock autopilot, you need no block. If its panel only reads back on its own datarefs, use shape (1).

If the stock engage does nothing (the sim sounds a disconnect tone), the autopilot is the aircraft’s own plugin. Look for which of its datarefs change when you press its buttons. Values that flip 0/1 or step through small integers are shape (2); datarefs that only read back while a command moves them are shape (3).

Finding and checking a mapping (apmap)

e3x-core apmap is the discovery and validation tool. It talks only to X-Plane’s Web API on the same computer. The installed e3x-core is not on your PATH, so run it by its full path; on Windows, in PowerShell: & "$env:LOCALAPPDATA\Programs\EmreliaE3X\core\e3x-core.exe" apmap probe (Linux: <install folder>/core/e3x-core apmap probe). e3x-core doctor prints the path. If X-Plane’s Log.txt says port 8086 was taken, add --port <the port it used>.

• apmap probe answers “why does my autopilot disconnect”. It names the loaded aircraft and where its e3x.json goes. It says whether the stock engage is writable and which mapping the E3X would use. It also lists the aircraft’s own autopilot datarefs.
• apmap validate --dir "<the aircraft's folder>" (or --profile <name>) checks a mapping the way the E3X would. It checks the JSON syntax first: a broken file turns the whole aircraft config off, not just this block. It then checks each error, every open TODO:, and each dataref and command. A dataref or command must exist (a near miss prints “did you mean …?”), be writable where you write it, and not be a text dataref. Validate before you reload.
• apmap list shows the bundled mappings, verified or draft.
• apmap record walks you through a sequence of autopilot actions (AP on and off, HDG, ALT, VS, FD, YD, the bugs). It reports which datarefs move for each. It then prints a draft autopilot block to paste, with a TODO: wherever it could not be sure. Run X-Plane windowed or on a second screen so you can reach the cockpit; --out <file> writes the draft to a file. It never writes your e3x.json.

After editing the block, disengage the autopilot, then reload the aircraft (Developer → Reload the Current Aircraft) and check AP Status.

Troubleshooting.

• The Messages list says “AP Unavailable”: the E3X pressed the aircraft’s autopilot and it did not engage. Either it is not X-Plane’s stock one, or a mapping value is wrong; AP Status says which, then run apmap probe. (AP green but the aircraft does not follow means a status read is true while the autopilot is off: re-check that value.)
• A steady red AP and the AP key does nothing: the autopilot has no power, so switch the avionics master on. master.available reads X-Plane’s autopilot-has-power flag, which follows the aircraft’s bus wiring and its avionics master switch; a definition that extends a bundled one inherits it. If your definition drives a plugin autopilot and the aircraft’s Plane Maker autopilot has no bus wiring, the flag reads 0 even with avionics on. Then write "master": {"available": null} and the E3X treats the autopilot as always available. A definition that binds available to another dataref must name one that exists: X-Plane reports a missing dataref as 0, which reads as permanently unpowered.

The E3X logs and ignores a bad autopilot block. An unknown profile name or a definition with errors falls back to auto-detection (and so, normally, to X-Plane’s own autopilot). AP Status shows the error count. Nothing on the flight displays goes dark.

Autopilot coupling (ap_native)

Key	Value	Effect
alt	true / false	true forces the autopilot’s native altitude mode; false makes the E3X drive altitude through the autopilot’s vertical-speed mode.
flc	true / false	The same for flight-level change.

Leave a key out to let the E3X detect the autopilot’s capability itself (the normal case). It applies to whichever autopilot mapping is in force, on its alt and ias channels (flc is the ias channel). A mapping without that channel ignores the key. See the Autopilot guide.

Engine display fields

These sit at the top level of an entry, beside install. Setting any of them gives the aircraft its own engine display: it replaces the profile the E3X would otherwise pick for a known aircraft type. Every field you set wins over what the sim reports. Fields you leave out come from what the sim reports, else from the defaults below (a four-cylinder Archer-style panel). Leave them all out to keep the automatic engine display.

Field	Type	Default	Meaning
engine_type	string	"piston"	"piston", "turboprop" or "jet"; picks the default gauge and CAS set.
engines	integer	1	Engine count.
engine_index	integer	0	Which of the sim’s engines to show.
cylinders	integer	4	Cylinder count.
fuel_capacity_gal	number	48.0	Usable fuel, US gallons.
fuel_tabs_gal	number	34.0	Fuel at the tabs, US gallons.
has_manifold_pressure	boolean	true	Show manifold pressure.
egt_probes	integer or null	null	EGT probe count (null: one per cylinder).
cht_probes	integer or null	null	CHT probe count (null: one per cylinder).
synthesis	string	"auto"	"auto" or "off".
tit	boolean	false	Show turbine inlet temperature.
temp_unit	string	"°C"	"°C" or "°F".
gauge_limits	object	built in	Per-gauge scale ends, bands and redlines — see below. Written by the Config page.
gauges	list	built in	Overlays the default set by id: a listed gauge replaces that gauge, a new id joins the set, and the others stay automatic. Hand-edited only.
cas	list	built in	Replaces the whole caution/advisory set (no merging). Hand-edited only.
fuel_type	string	Auto	"avgas" or "jet-a"; sets the density the sim’s fuel mass converts to gallons with. Auto: Jet-A on a turbine, else avgas, so a diesel piston declares "jet-a". Written by the Config page.
ff_unit	string	Auto	The unit of the aircraft’s authored fuel-flow arcs: "gph" or "lb/hr", which also makes lb the default Fuel display unit. Auto: the .acf’s flag on a turbine. Hand-edited only.
temp_units	object	Auto	The unit the sim streams an engine temperature in, where the aircraft’s own flag misstates it: {"oil": "F"}. Keys are oil, cht, egt; values are "C", "F". Hand-edited only.
gravity_feed	boolean	false	The engine is gravity-fed: no fp (fuel pressure) gauge, unless gauges lists one. Hand-edited only.

A gauges entry needs id, label, kind, source, min and max. It can add unit, zones (a list of {"from", "to", "color"} with color green, yellow, red or white (advisory)), redline, low_redline, decimals and requires_mp. kind is one of arc, bar, dial, numeric, bars_per_cylinder. A cas entry needs all of id, text, level (warning, caution or advisory), source, compare (gt or lt) and limit.

The E3X does not check these values when the file loads, so stick to the ones listed. gauges and cas are hand-edited only — the Config page never rewrites them. To pin a band on an otherwise automatic gauge, use gauge_limits below instead.

Gauge limits (gauge_limits)

Pins an engine gauge’s reference values — its scale ends, colored bands and redlines — without replacing the whole gauge. One entry per gauge id (rpm, map, ff, oil_press, oil_temp, fp, egt, cht, fuel_l, fuel_r, fuel_3, fuel_4, volts, amps). On a turbine: trq, itt, ng, np, n1, n2. Each entry is a ladder of band edges from low to high, in the gauge’s own unit (temperatures in °C):

Key	Meaning
min, max	The scale ends.
red_lo	Top of the low red band, and the low redline (warning at or below).
yellow_lo	Top of the low yellow band.
white_lo	Top of the low white band (advisory, no caution).
green_lo, green_hi	The green (normal) band.
white_hi	Bottom of the high white band.
yellow_hi	Bottom of the high yellow band.
red_hi	Bottom of the high red band, and the redline (warning at or above).

The E3X pins only the keys you write; every other band edge still follows the sim’s authored arcs (or the built-in default). To drop a band, make it zero-wide: "yellow_lo": 0 on a scale that starts at 0 removes the low yellow. The Config page’s Engine tab writes this block through one “<GAUGE> Limits” popup per gauge the aircraft draws. It shows no MAP row without a manifold-pressure gauge, and no CHT row on a jet. A gauge the ladder cannot describe (two yellow bands on one side) still needs a hand-written gauges table.

Shipped templates

The installer and install aircraft-config --install <name> start from one of these. Each is only a starting point: edit the file afterward.

“GSA 28 roll + pitch” is the pair of autopilot servos (see the box types). Power wiring says whether the template carries a recommended power block; one without it models no bus power until you add one.

Template	Equipment	Power wiring	Seeded by default for
default	GDU 460, GSU 25, GEA 24	No	Any aircraft the setup wizard does not recognize
c172_stock	2× GDU 460, GSU 25, GEA 24, G5 standby, GMC 507, GSA 28 roll + pitch, GNS 530 (unit 1), GNS 430 (unit 2)	Yes	Cessna 172 SP: Cessna_172SP.acf, Cessna_172SP_seaplane.acf (the "*" entry)
c172_g1000_stock	2× GDU 460, GSU 25, GEA 24, G5 standby, GMC 507, GSA 28 roll + pitch, G1000 (unit 1)	Yes	Cessna 172 SP G1000: Cessna_172SP_G1000.acf (its own entry in the same file)
c172_e3x	2× GDU 460, GSU 25, GEA 24, G5 standby, GMC 507, GSA 28 roll + pitch, GNS 430 (unit 1)	Yes	The generated Cessna 172 SP E3X
rv10	2× GDU 460, GSU 25, GEA 24, G5 standby, GMC 507, GSA 28 roll + pitch	Yes	Van’s RV-10: RV-10.acf
sr22	2× GDU 460, GSU 25, GEA 24, G5 standby, GMC 507, GSA 28 roll + pitch	Yes	Cirrus SR22: Cirrus SR22.acf
baron58	2× GDU 460, GSU 25, GEA 24, G5 standby, GMC 507, GSA 28 roll + pitch, GNS 530 (unit 1)	Yes	Beechcraft Baron 58: Baron_58.acf
c90b	2× GDU 460, GSU 25, GEA 24, G5 standby, GMC 507, GSA 28 roll + pitch	Yes	Beechcraft King Air C90B: C90B.acf
sf50	2× GDU 460, GSU 25, GEA 24, G5 standby, GMC 507, GSA 28 roll + pitch	Yes	Cirrus Vision SF50: CirrusSF50.acf
citation_x	2× GDU 460, GSU 25, GEA 24, G5 standby, GMC 507, GSA 28 roll + pitch	Yes	Cessna Citation X: Cessna_CitationX.acf
lancair_evo	2× GDU 460, GSU 25, GEA 24, G5 standby, GMC 507, GSA 28 roll + pitch	Yes	Lancair Evolution: N844X.acf
c172_dual_gns430	GDU 460, GSU 25, GEA 24, GNS 430 (unit 1), GNS 430 (unit 2)	No	— (two add-on GNS 430s)
c172_g1000	GDU 460, GSU 25, GEA 24, G1000 (unit 1), GNS 430 (unit 2)	No	— (an add-on GNS 430 beside the G1000)
cub_rxp_tds	GDU 460, GSU 25, GEA 24, GNS 430 (unit 1), GTN 650 (unit 2)	No	— (add-on navigators)
dual_adahrs	GDU 460, 2× GSU 25, GEA 24, G5 standby	No	—
gsu73	GDU 460, GSU 73 carrying the engine data, no GEA 24	No	—
nav_demo	GDU 460, GSU 25, GEA 24, GTN 750 — for the desk demo	No	—
alt_fail_shed	2× GDU 460, GSU 25, GEA 24, GMC 507, GSA 28 roll + pitch — for the bus-power demo	Yes	—

The last column is what the installer and the setup wizard pick by themselves, matched on the aircraft’s .acf file names. The bus wiring of each stock template is in the power block table. A folder holding several stock models gets one entry per model where their templates differ. Templates marked “—” are never picked automatically; name them with --install. From the command line without --install, an aircraft the E3X does not recognize gets the c172_e3x boxes with no bus wiring.

Examples

What Setup writes for the generated Cessna 172 SP E3X (the _comment line shortened; it sits beside variants, outside the entries):

{
  "_comment": "This is the per-aircraft E3X config. ... Options: https://emrelia.com/docs/aircraft-config/",
  "variants": {
    "*": {
      "name": "Cessna 172 SP E3X",
      "install": {"lrus": [
        {"id": "gdu1", "type": "GDU460", "power": ["bus1", "bus2"]},
        {"id": "gdu2", "type": "GDU460", "power": ["bus1"]},
        {"id": "adahrs1", "type": "GSU25", "power": ["bus1", "bus2"]},
        {"id": "gea1", "type": "GEA24", "power": ["bus1", "bus2"]},
        {"id": "g5_1", "type": "G5", "role": "standby"},
        {"id": "gmc1", "type": "GMC507", "power": ["avn"]},
        {"id": "servo1", "type": "GSA28", "axis": "roll", "power": ["avn"]},
        {"id": "servo2", "type": "GSA28", "axis": "pitch", "power": ["avn"]},
        {"id": "gns430_1", "type": "GNS430"}
      ]},
      "power": {
        "buses": {"bus1": {"xp_bus": 0}, "bus2": {"xp_bus": 1}, "avn": {"xp_bus": 0}},
        "avionics_master": ["avn"]
      }
    }
  }
}

Two ADAHRS with a G5 standby (the sensor source picker appears):

{
  "variants": {
    "*": {
      "name": "My RV",
      "install": {"lrus": [
        {"id": "gdu1", "type": "GDU460"},
        {"id": "adahrs1", "type": "GSU25"},
        {"id": "adahrs2", "type": "GSU25"},
        {"id": "gea1", "type": "GEA24"},
        {"id": "g5_1", "type": "G5", "role": "standby"}
      ]}
    }
  }
}

A GSU 73 carrying the engine data, temperatures in °F, and the autopilot’s altitude mode forced to native:

{
  "variants": {
    "*": {
      "name": "My Bonanza",
      "install": {"lrus": [
        {"id": "gdu1", "type": "GDU460"},
        {"id": "adahrs1", "type": "GSU73", "eis_coupled": true}
      ]},
      "temp_unit": "°F",
      "ap_native": {"alt": true}
    }
  }
}

Pinned V-speeds and a couple of gauge limits, everything else left to detection:

{
  "variants": {
    "*": {
      "name": "My RV-10",
      "vspeeds": {"vne": 200, "vno": 166, "vfe": 96, "vg": 80},
      "gauge_limits": {
        "cht": {"yellow_hi": 215, "red_hi": 238},
        "rpm": {"red_hi": 2700}
      }
    }
  }
}

When the file has an error

Nothing shows on the flight displays: the E3X writes problems to the logs and falls back to defaults for the part that failed. The Config page’s status line does name a file it could not parse, with the offending line. The plugin’s lines start with e3x companion: in X-Plane’s Log.txt.

Problem	What happens
No e3x.json beside the .acf	The E3X does not start for that aircraft (plugin logs no e3x.json beside <aircraft>).
File larger than 256 KiB	Skipped; the default install applies.
Not valid JSON, or not a JSON object	The E3X ignores the whole file.
Anything wrong in install. That means unknown type or role, an id without a trailing digit, a duplicate id, or a missing id or type. It also means a bad sources entry or eis_coupled on a type that cannot carry engine data. The same goes for a GSA28 without a valid axis (or two servos on one axis), or an axis on any other type.	The E3X ignores the whole equipment list and the default install applies; the other sections still apply. The Config status line reads “e3x.json LRU install unusable: fix the file”.
A bad gauge_limits entry, or a fuel_type, ff_unit or temp_units value off its list	The E3X drops only that value; the rest of the engine section still applies.
A wrong type or a missing required key in the other engine fields, gauges or cas	The E3X ignores the engine section and uses its detected or built-in engine settings.
Anything wrong in the bus wiring. That means a power block that does not parse, or power inside install. It also means a box power list naming an undeclared bus or with no power block.	The E3X drops only the wiring: the boxes stay and it models no bus power. The Config status line reads “e3x.json power wiring ignored: fix the file”.
A bad autopilot block	Ignored; the autopilot is auto-detected, and AP Status shows the error count.
A bad value in vspeeds	That speed falls back to Auto; the others still apply.
A key the E3X does not know	Ignored.
The aircraft folder is not writable	The edit applies for this run only and is lost on relaunch. The E3X logs it and the Config status line reads “<folder> read-only: edit NOT saved”.

When it applies the file, the E3X logs the equipment it is using, ending in (per-aircraft e3x.json). With no usable equipment list, which includes a valid file with no install or power block, it ends in (default (no e3x.json)).

Older versions: radios in the settings file

Before the Config page, the radio enables were a global E3X setting (Menu → Setup → Radios) kept in the E3X’s own settings.json. They are now per aircraft, in this file. The E3X carries an older settings file’s radio choices into the e3x.json of the first aircraft you fly after updating. It then drops them from the settings file, and every other aircraft starts with all radios on. The Setup → Units choices moved into this file the same way.